03 / Symptom to cause
Begin with what users and operators can actually see.
Diagnostic paths for intermittent errors, stuck work, unreachable deployments, stale data, and local-versus-remote mismatches.
API intermittently returns 502: trace the proxy boundary
Diagnose intermittent HTTP 502 responses at the proxy boundary by distinguishing upstream silence, upstream crash, and proxy-side framing mismatches. The guide treats 502 as a Bad Gateway signal that the proxy synthesized because it could not assemble a valid response from the origin, and walks from request-shape inspection to upstream socket evidence before any configuration change.
Open guide →Background job remains running forever: find the missing completion edge
A symptom-first guide for engineers whose queue worker starts a job but never reports it as completed or failed. It focuses on the missing completion edge: the place in the worker lifecycle where the job is supposed to transition from active to a terminal state, and where the handler silently fails to call it.
Open guide →Cache appears updated but users see old data
When an engineer has confirmed that a cache write succeeded, yet end users continue to observe the previous value, the issue is almost always a routing or layering problem rather than a failed write. The cache may be perfectly updated on one node, key, or layer, but the reader is hitting a different replica, a stale sibling cache, or an HTTP/browser cache that sits in front of the application.
Open guide →CI passes locally but fails remotely: compare execution context
Diagnoses cases where a build or test suite succeeds on a developer's machine yet fails on a remote CI runner. The core failure mode is a mismatch between the two execution contexts: dependencies, permissions, environment variables, file layout, timing, or OS-level behavior. The guide walks from first symptom (a red CI run with green local tests) to verification that the remote environment has been aligned with the local one, using only the workflow file as the source of truth.
Open guide →Container starts and exits immediately: read the process lifecycle
A container that returns to the shell seconds after `docker run` almost always means its PID 1 foreground process terminated. Docker is doing its job; the application inside is not. The lifecycle is observable in `docker ps -a`, in `docker logs`, and in the image's configured Entrypoint and Cmd, so diagnosis starts in metadata before it touches code.
Open guide →Database queries suddenly queue: locate the shared bottleneck
When PostgreSQL throughput collapses without a code deploy, queries typically pile up behind a shared resource: locks held by a long transaction, a saturated connection pool, I/O backpressure on the storage layer, or a plan regression that turns a millisecond scan into a multi-second one. This guide walks database engineers from the first wait_event observation through pg_stat_* evidence to the specific bottleneck, then defines proof criteria before any change is shipped.
Open guide →Deployment succeeds but the application is unreachable
A deployment that finishes without errors can still leave the application unreachable. The build artifact was produced and accepted by the platform, but traffic never reaches the process because of binding, routing, health-probe, or post-deploy startup failures. Diagnose by separating pipeline success from runtime reachability.
Open guide →GraphQL request returns null without an obvious error
GraphQL responses can return null for a field while leaving the errors array empty or empty-looking, leaving engineers with partial data and no obvious failure signal. This guide explains how to distinguish a resolver returning null, an authorization rule masking data, and spec-level null bubbling, then walks through evidence collection, isolation, and verification.
Open guide →Login works once then redirects forever: trace the session contract
Browser appears to authenticate successfully on the first request but is then bounced between the identity provider and the application indefinitely. The root cause is almost always a disagreement in the session contract: cookies that the server believes it set are not the cookies the middleware or callback handler observes on the next hop.
Open guide →CPU is low but requests time out: look beyond compute saturation
CPU utilization is low but client requests still time out, indicating the latency is bounded by something other than compute. This guide frames the symptom as a resource-bound mismatch: time is spent waiting on I/O, locks, connection pools, or downstream deadlines rather than CPU cycles. The first ten minutes are spent measuring wait states and queue depths before considering any code change.
Open guide →