quinzee.cloud

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.

Administrator’s guide

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.