Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.
16. Troubleshoot a connection or workflow
Work from the network inward: correct environment, DNS, TLS, authentication, resource readiness, then the requested operation. Preserve the failing step, status/error code and trace ID; keep tokens, passwords and signed URLs out of shared diagnostics.
Step 1: identify the environment
Chapters 2–11 use .local/application/development; the messaging lab in
chapters 12–13 uses the standalone cloud. make cloud-up and the default
make qhq-run use .local/quinzee. Each has its own credentials and CA. The
application environment's network, DNS subnet and cloud port are recorded in
environment.json; do not assume it uses 11443 or 172.29.53.53.
Inside the chapter 3 SDK container:
getent hosts management.azure.com
curl --fail --silent --show-error https://management.azure.com/health
The address must be the local cloud container, and the response must name
quinzee.cloud. If not, stop credentialed requests until the client is using
Quinzee DNS and the matching public trust bundle.
Step 2: match the symptom
| Symptom | Check and action |
|---|---|
| SDK sees real Azure or cannot find the tenant | Check both --network and --dns. Enable Azure emulation on a standalone cloud. The application helper enables it for its own environment. |
SSL certificate problem or .NET TLS failure |
Check the exact environment's CA and SSL_CERT_FILE; verify the hostname matches the certificate. Do not disable verification. |
| Monitoring hostname fails while other services work | Certificates issued before monitoring names were added may need deliberate renewal and refreshed client trust. |
| Browser certificate warning | Import the public development CA printed by this environment. Grafana has a separate CA under .local/observability. |
invalid_client |
The tenant/client/secret must all come from this environment. A browser access token is not a client secret. |
| 401 after cloud restart | Recreate the client/credential or allow its refresh path; old signing-key tokens are invalid. |
| Monitoring query rejects an ARM token | Use LogsQueryClient with TokenCredential; it requests the correct audience. |
| 503 for one service | Check QHQ Modules; the responsible service may be unloaded. |
| Deployment is Running/Updating for a long time | Keep the supervisor running; inspect engine heartbeat and operation error. Native provisioning fails explicitly after its readiness timeout. |
| MySQL certificate revocation error | Ensure the supervisor's signed CRL endpoint is reachable on the private bridge; retain VerifyFull. |
| SQL/Redis host cannot be reached from the host desktop | Native ports are private. Run the client on the engine network and use its DNS hostname. |
| A stopped database is still listed | Resource existence and native readiness differ. Start it and wait for the operation. |
| Queue receive returns no message | It may be leased, expired, consumed by another worker or in another queue/account. Peek is not a reservation. |
| Message delete/update rejects the pop receipt | Retain the latest receipt returned by receive or update; do not reuse an earlier one. |
| Service Bus HTTPS works but the SDK cannot connect | Check the separate AMQP/TLS listener, forwarded port, private DNS and CA. Select AmqpTcp; WebSockets are unsupported. |
| Service Bus settlement reports a lost lock | Retain the current received message/lock, settle before expiry, and renew before long processing. Redelivery requires idempotent handlers. |
| Service Bus message disappears from the active queue | Inspect $DeadLetterQueue, TTL and other consumers. A running Functions trigger competes with manual receivers. |
| Function app stays Updating or fails readiness | Keep the helper running on the matching state/network; check image registration. A missing helper times out after 180 seconds. |
| HTTP function returns 401 | Supply its function key, obtained through ARM host/default/listkeys, in x-functions-key. An ARM token is not an invocation key. |
| HTTP function returns 503 or 502 | Check app state, helper heartbeat and upstream TLS/reachability. A stale helper stops forwarding; keep certificate verification enabled. |
| Function queue inspection is empty after restart | The example keeps its received messages in memory. Use persistent application storage for durable results. |
| Deleted function name cannot be reused | Tombstones reserve names; choose a fresh name rather than editing private runtime state. |
| Blob overwrite or setting update returns 412 | An ETag condition failed. Re-read and resolve the concurrent change. |
| Blob SAS returns 403 | Check expiry, scope, permissions, signing key and HTTPS; do not log the signed URL while diagnosing it. |
| Secret name cannot be recreated | A soft-deleted secret may need recovery or intentional purge. |
| Query returns unsupported syntax/result-too-large | Use the documented KQL stages and add a filter, take, or aggregation. |
| No telemetry from a short C# program | Keep the provider alive, end the activity, flush it and check the component connection string/credential. Set TracesPerSecond = null and SamplingRatio = 1 for 100% sampling; the rate limit otherwise overrides the ratio. |
| QHQ request trace is missing | The native history holds only 128 recent requests; use exported traces for a longer view. |
| Grafana has no record for an Application Insights event | The two destinations are separate; configure an OTLP exporter if that application should also send to the platform stack. |
| Application Verify fails on a second attempt | Verification consumes the recovery message. Run the full workflow to create a new one. |
| Shutdown cannot remove a Docker network | Exit SDK/debug containers still attached to that network, then stop the owning environment. |
Step 3: resolve setup errors
If docker-dotnet:latest is missing, build it in the Triglav-OS repository with
make -j8 docker-dotnet, or set TRIGLAV_OS_DIR so Quinzee can load the export.
A runtime image does not contain the .NET SDK; use the Microsoft SDK container
for dotnet build and dotnet run.
If restore/build cannot download packages, check network access and the exact locked package sources. Do not replace a checksum to make a failed verification pass. A QHQ build also needs access to the independent Simple Git repository; server-only Docker builds do not need that UI package.
For QHQ's rasta did not start, check the graphical session, SDL2 availability
and build/qhq/rasta.log. For a used port, stop the process you own or select a
different environment port; do not kill unrelated applications.
Step 4: reproduce with the supplied application
Run make application-test for a disposable complete workflow, or
make application-observability-test for the additional backend and outage
checks. These commands create their own groups, networks and engine resources.
They clean successful disposable application state; a failed run retains private
logs/results under .local/application/test-* for diagnosis. The optional
telemetry stack is separately operated; stop it with make observability-down
when you are done.
For messaging, use make service-bus-sdk-test; for real HTTP/queue-trigger
execution, follow the prerequisites and run command in the
Functions chapter. These
fixtures use isolated state rather than the persistent application environment.
Share the failed operation/status and a redacted trace ID, not a copy of the private environment directory.