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.
14. Diagnose failures from the outside inward
Start with a single failing operation and identify its boundary. Repeatedly changing multiple settings destroys evidence. Record the origin, timestamp, resource ID and trace ID, but omit passwords, tokens and private response bodies.
Step 1: use the symptom to choose the next check
| Symptom | Check first | Meaning and next action |
|---|---|---|
| Connection refused | Process, bind IP, host/container port mapping | Start the intended listener; verify you are in the correct lab |
| TLS chain failure | Matching public CA bundle | Trust the intended issuer in this client; keep verification enabled |
| TLS hostname failure | URL/DNS/SAN agreement | Use the certificate's name or issue the correct certificate |
| 401 | Credential, tenant, audience, expiry | Obtain the correct service token; an ARM token is not a Graph token |
| 403 | Principal state and scoped assignment | Check app roles versus Azure RBAC and the resource scope |
| 404 | Host routing, path, API version/resource existence | Do not assume the same path works on every service hostname |
| 409 unloading | RequiredBy list | Unload dependants first; stop external work separately |
| 409 creating | Existing name, tombstone, duplicate assignment | Inspect the actual ID; use a new intended name only when appropriate |
| Updating then Failed | Helper heartbeat, image approval, engine/readiness error | Fix the external dependency and redeploy |
| LDAP bind fails | TLS, DN, account enabled/password/throttle | Use the generated DN and shared account; do not reset a second LDAP password store |
| Directory fails after DB recovery | Writer connection/marker | Restart cloud with the original destination configuration |
| Empty telemetry | Workspace/component, token audience, exporter/drop counters | Distinguish missing events from unsupported query or eviction |
| Queue work repeats | Lock/visibility expiry, missing settlement | Make processing idempotent and settle with the current token |
Step 2: check process health without exposing state
Use /health, /ready, QHQ status and the operator's service logs. In the
standard environment, docker compose logs quinzee-cloud quinzee-dns shows the
frontends. Helper output belongs to its own terminal/service log. A useful
incident report includes the failed API/resource and a redacted trace excerpt,
not credentials.json, a private settings dump or a full state archive.
Step 3: understand the implementation details that affect operations
HTTP handlers run on a bounded worker executor. Queueing can contribute latency before a handler runs, so inspect transport and executor metrics as well as service duration. Large bodies, slow clients and over-capacity work are bounded; there is no supported startup knob for every library-level limit.
Durable stores commit mutations before reporting success where their contract requires it. SQLite-backed tables, broker messages and Event Grid delivery rows need their full journal state for backup. A module unload removes routes/workers but retains durable state. An external runtime status is accepted only for its current generated revision; stale status cannot resurrect a deleted or replaced app. Tombstones prevent helpers from recreating deleted resources after restart.
The directory's one-writer lease and no-fallback marker protect permission consistency. Failure to authenticate during a database outage is intentional. Do not turn a fail-closed security boundary into stale authorization by deleting its state marker or copying an old directory.json over current records.
The native engine and hosting helpers validate fixed request schemas and approved images. Giving the cloud a Docker socket bypasses that design and is not an operational fix. Managed identity headers exist only at the protected workload boundary; copying one into a developer's terminal is not the supported login flow.
Step 4: separate test environment restrictions from product defects
make test runs debug checks; release and ASan profiles check other build modes.
ThreadSanitizer can fail before application code because its runtime requests
ADDR_NO_RANDOMIZE and the execution environment denies it. Record that as an
uncompleted sanitizer run. Do not claim it passed and do not weaken ASLR or
container controls as a routine troubleshooting shortcut. The repository's
TSan exception requires explicit approval.
Step 5: collect a reproducible report
State the build revision, OS/architecture, selected modules, relevant public configuration, operation sequence and expected/actual behavior. Reproduce with synthetic data in a disposable environment. For a new client library version, re-run its compatibility exercise; a compiling SDK call can still use an unsupported API shape. Preserve logs privately and share only the minimal redacted information needed to reproduce the failure.