Troubleshooting Guide

Developer Portal build fails: OpenAPI spec missing

Run the build from the repository root or from web/qvtm-developer-portal. The portal expects OpenAPI specs under docs/specs/openapi.

cd web/qvtm-developer-portal
npm run build

The runtime and trust spec names are:

• qvtm_runtime_protocol_sdk_api_v1.yaml
• qvtm_trust_verifier_sdk_api_v1.yaml

TypeScript SDK validation fails

Run from the SDK workspace:

cd sdk/typescript
npm ci
npm run validate
node scripts/validate-all.mjs

Do not rely on globally installed TypeScript. The SDK release gate uses local package dependencies.

Swift tests cannot find Package.swift

Run Swift tests from the Swift package directory:

cd sdk/swift/control-plane
swift test

Rust marker mismatch

If a Rust test reports an older SDK marker, update the test expectation to the current release marker and rerun:

cd rust
cargo test -p qvtm-client-core

Live E2E fails

The TypeScript customer integration example can run as a dry-run. Live mode requires a reachable Control Plane and a backend-only provisioning token.

export QVTM_CONTROL_PLANE_URL=http://127.0.0.1:3100
export QVTM_PROVISIONING_TOKEN=<token>
node sdk/examples/typescript/customer-integration-e2e.mjs