01 / Error diagnostics
Start with the error, then find the boundary that failed.
Exact error-message guides for tracing what the runtime, database, container, or CI system is telling you.
CSRF origin check failed: compare browser origin and server policy
A state-changing HTTP request is rejected because the server's CSRF origin check compared the request's browser-supplied Origin (and/or Referer) against its allow-list and found a mismatch, or because a required token was missing or unreadable. The guide explains how the comparison is performed, how to distinguish an origin/referer rejection from a token rejection, and how to verify the server's policy without weakening defenses.
Open guide →Docker name is already in use: identify the stale container owner
Investigates the Docker CLI error "name is already in use by container" when `docker run` rejects a requested container name. Explains why the daemon keeps a name reserved even after a container exits, how to distinguish a stale, dangling container from a live one, and how to verify ownership before any removal action. Frames the failure as a naming-ownership problem, not a port or image problem.
Open guide →Docker exec format error: compare image architecture and runtime
Diagnose Docker "exec format error" by comparing image architecture against the host runtime. Distinguish ELF/architecture mismatches from shebang and binary-format failures using inspect, uname, and platform metadata before considering rebuilds or emulation.
Open guide →Docker no space left on device: separate image, layer, and volume pressure
Docker "no space left on device" is rarely a true disk-full event — it is a storage-driver allocation failure where the container runtime cannot claim new space on the filesystem backing images, build layers, writable container layers, volumes, or the build cache. The error is a category, not a diagnosis: the same string surfaces from five distinct storage boundaries, and treating them as one problem leads to safe-looking destructive commands that do not address the actual pressure point. This guide separates image pressure (registry pulls, dangling layers), layer pressure (overlay2 upperdir/workdir), volume pressure (named volumes, bind mounts), build-cache pressure (BuildKit), and thin-pool pressure (devicemapper). Triage begins with identifying which boundary raised ENOSPC and which filesystem the daemon logged the error against, not with `docker system prune`.
Open guide →GitHub Actions artifact not found: trace the producer-consumer run boundary
A GitHub Actions artifact not found error almost always signals a boundary mismatch between the producing run and the consuming run or job. The artifact, the run id, or the reference used to fetch it is anchored to a different execution context than the consumer expects. Treat this as a producer/consumer boundary problem before changing upload or download steps.
Open guide →GitHub Actions secret not available: inspect the workflow trust boundary
A GitHub Actions workflow fails with a "secret not available" indicator because the triggering event, the workflow's permission scope, or the calling context cannot deliver the named secret at the point of evaluation. This playbook walks engineers through the trust boundary that governs secrets — event type, job scope, reusable workflow call, environment, and the expression evaluation context — and gives a decision tree that separates misconfiguration from deliberate restriction.
Open guide →GraphQL validation error: locate the schema-query mismatch
Diagnose a GraphQL validation error by mapping the exact point where a query no longer satisfies the schema, before any resolver runs. This guide isolates the parsing-vs-validation boundary, names the concrete fields involved, and prescribes read-only checks so each candidate cause can be eliminated with observable evidence.
Open guide →Java ClassNotFoundException at runtime: compare the launch classpath
A runtime ClassNotFoundException means the JVM can compile against a class but cannot locate it when the application launches. The diagnostic core is comparing the compile-time classpath against the launch classpath and identifying exactly which artifact, module, or classloader chain is missing the requested class.
Open guide →Java IllegalStateException: identify the violated lifecycle state
IllegalStateException in Java is raised when a method is invoked while the target object, stream, iterator, or framework component is in a lifecycle state that disallows the operation. Diagnosing it requires pinpointing the exact violated invariant, since the exception itself only reports that an operation was attempted at the wrong time rather than naming the broken rule.
Open guide →Kubernetes CrashLoopBackOff: distinguish process exit from probe failure
CrashLoopBackOff is Kubernetes reporting that a container has repeatedly failed its lifecycle contract, but the contract can be violated in two structurally different ways: the process exited non-zero, or the probe declared it unready. This guide gives a defensible way to separate those causes from kubectl describe, events, and the container's last termination reason before changing any configuration.
Open guide →Kubernetes OOMKilled: correlate the limit with the process lifetime
Kubernetes terminates a container with OOMKilled when the kernel detects memory usage exceeding the configured cgroup limit. Correlate the exit reason, the container's memory limit, and the process's working-set growth over its lifetime to distinguish a legitimate spike from a misconfigured boundary or a leak.
Open guide →Kubernetes readiness probe failed: find why traffic was withheld
Kubernetes readiness probes determine whether a running pod should receive Service traffic. When a probe fails, the pod stays Running with Ready=False and is removed from a Service's endpoint set, effectively withholding traffic without indicating a crash. This guide walks through identifying which probe type failed, why it failed, and how to restore service membership with evidence-based decisions.
Open guide →Node.js ECONNREFUSED: separate a dead listener from a blocked route
Distinguishing a Node.js ECONNREFUSED that points to a dead local listener from one that points to a blocked upstream route, using socket-level evidence rather than guesswork. The guide frames ECONNREFUSED as an operating system response (no listener accepted the SYN), then walks through the two most common causes: a target process that is down or bound elsewhere, and a route or firewall that silently drops traffic so the client never receives a RST.
Open guide →Node.js address family error: distinguish IPv4 and IPv6 binding
This guide distinguishes Node.js address-family mismatches between IPv4-only and IPv6-only sockets, focusing on the failure mode where a listener or client requests an address family unavailable on the active host. It covers diagnostic boundaries, evidence-gathering steps, and conditional fixes anchored to Node's documented DNS, net, and error semantics. The intent is to prevent misdiagnosis between DNS resolution failures, dual-stack socket binding conflicts, and intentional family pinning in libraries such as net, http, https, dgram, and tls.
Open guide →Node.js ERR_HTTP_HEADERS_SENT: find the second response write
ERR_HTTP_HEADERS_SENT fires in Node.js when application code attempts to write, set, or end the response after the first byte of headers has already been flushed. This guide focuses on locating the second response write inside async code paths, verifying the offending boundary, and applying conditional fixes that do not mask the underlying double-response bug.
Open guide →Node.js ERR_INVALID_URL: trace malformed URL construction
Node.js throws ERR_INVALID_URL when url.parse, WHATWG URL, http.request, https.request, fetch, import, or worker bootstrap code receives a string the engine cannot parse as an absolute URL with a recognized scheme. This guide explains the observable failure boundary, how to trace the malformed URL back to its construction site, and how to verify the fix without changing runtime semantics.
Open guide →Node.js write after end: locate the late stream producer
This guide explains Node.js's "write after end" stream error: a Writable receives data or signals after end() (or destroy()) has already been called. The argument is that the error is rarely about the call site that throws; it is about a late producer that still holds a reference to a closed sink. The guide frames diagnosis as producer-tracing, not stack-trace reading.
Open guide →Node.js ETIMEDOUT: identify which network deadline expired
Node.js ETIMEDOUT errors are ambiguous by default: the same error code can be raised by socket connect timeouts, DNS resolution deadlines, HTTP request timeouts, or upstream server keep-alive deadlines. This guide shows engineers how to read the surrounding stack, code, and options object to identify which deadline actually expired before changing any timeout value.
Open guide →OAuth invalid_grant: identify the expired or mismatched authorization state
Diagnose and resolve OAuth `invalid_grant` errors by distinguishing expired authorization codes, replay attempts, redirect URI mismatches, client credential drift, and PKCE/state mismatches. The guide provides an evidence-first triage sequence for engineers reading authorization server responses, server logs, and browser artifacts to pinpoint which precondition failed before applying a targeted fix and proving it with a controlled replay.
Open guide →PostgreSQL statement timeout: locate the waiting phase
Diagnose PostgreSQL statement_timeout by locating the precise phase in which a query is cancelled: parsing/planning, executor wait on a lock or I/O, executor active run time, or client-side abort. Walks from the SQLSTATE 57014 surface through pg_stat_activity, pg_locks, and wait-event analysis to a targeted remediation that distinguishes server enforcement from client/network cancellation.
Open guide →PostgreSQL duplicate key violation: determine whether retry or data repair is correct
When PostgreSQL rejects a write with a duplicate-key error, the engineering decision is whether to retry safely (transient conflict) or repair the underlying constraint/row state (true data conflict). This guide walks through recognizing the SQLSTATE class, distinguishing soft contention from hard violations, and choosing a remediation path gated on evidence rather than heuristics.
Open guide →PostgreSQL invalid text representation: find the input boundary
This guide explains PostgreSQL's class-22 "invalid_text_representation" errors. The failure mode is a string value that cannot be parsed into the declared column or parameter type (e.g. INTEGER, DATE, JSONB, NUMERIC, BOOLEAN). The fix model is to find the input boundary where the bad string first enters the SQL pipeline, prove which cast rejected it, and constrain the producer so the value never reaches the server without validation. The approach is conservative: read the error in context, identify the cast site, fix the producer rather than masking the error, and add a regression check.
Open guide →PostgreSQL lock not available: distinguish NOWAIT from deadlock
When a PostgreSQL statement fails with a lock-not-available error, the message wording tells you which mechanism fired. NOWAIT and SKIP LOCKED surface SQLSTATE 55P03 ("lock_not_available"), while a true deadlock surfaces SQLSTATE 40P01 ("deadlock_detected"). Conflating them leads to bad fixes: retrying a NOWAIT failure as if it were contention wastes attempts, and treating a deadlock as simple contention misses the cycle in the lock graph. The fix path is conditional on the SQLSTATE, the wait policy, and the lock graph captured in pg_stat_activity and pg_locks.
Open guide →PostgreSQL remaining connection slots reserved: find the pool oversubscription
PostgreSQL rejects new client connections with "FATAL: remaining connection slots are reserved for non-replication superuser connections" when the server reaches max_connections. The guide frames the error as a pool-oversubscription signal, separating client-side pool misconfiguration from server-side capacity planning, and walks through evidence collection, triage, and verification.
Open guide →PostgreSQL serialization failure: read the conflicting transaction evidence
PostgreSQL raises a serialization failure when the SERIALIZABLE isolation engine detects that the read-write dependencies your transaction accumulated would produce an outcome that could not have happened if all transactions had run one at a time. The database aborts only the transaction that lost the safety check, returns SQLSTATE 40001, and forces your application to retry. Diagnosis is therefore not "find the bug" but "reconstruct the read-write conflict graph from the surviving logs and statistics views" so you can either change the order of operations or accept retries as a normal control-flow signal.
Open guide →Python AttributeError on None: trace the first missing-value branch
AttributeError: 'NoneType' object has no attribute 'X' is raised when code performs attribute access on a value bound to None instead of an expected object. The job is not to silence the traceback but to trace the first missing-value branch: the assignment, return, or lookup that left a None where the code path assumes a fully constructed object, and then to confirm whether None is a legitimate sentinel or evidence of a real fault upstream.
Open guide →Python circular import: find the partially initialized module
Python's "partially initialized module" ImportError is raised when module A imports module B during its own initialization, and module B in turn imports (or re-imports) module A before A has finished defining its top-level names. The interpreter refuses to hand back a half-built module object and surfaces the ImportError naming the cyclic pair. Because Python's import system is deterministic and synchronous, the cycle is reproducible and traceable; the engineering task is locating the exact import statements that close the loop, deciding whether the cycle is structural (bad layering) or incidental (a top-level import that should live inside a function), and proving the fix by importing both modules from a clean interpreter.
Open guide →Python ConnectionResetError: distinguish peer reset from local shutdown
Python raises ConnectionResetError when an established socket is closed by the peer with a TCP RST or when the local host tears the connection down before the application expects it. This guide shows engineers how to separate peer-reset from local-shutdown signals using errno, WSAECONNRESET, and peer address evidence, then how to verify each path before changing code.
Open guide →React hydration mismatch: compare server and browser inputs
A React hydration mismatch occurs when the HTML produced on the server does not match what the client renders during hydration. This guide explains how to identify where the divergence originates, separate environment-dependent causes from code-level causes, and verify the fix by observing that React no longer reports hydration warnings or recovers from the mismatch.
Open guide →React maximum update depth exceeded: isolate the feedback loop
React's "Maximum update depth exceeded" error fires when a component schedules another render before the current render settles, usually because a render-phase side effect, dependency-driven effect, or setState-in-render pattern loops back into state. This guide isolates that feedback loop using the official useEffect semantics as the anchor for what counts as a side effect.
Open guide →Redis CROSSSLOT: find the multi-key command's slot mismatch
Redis Cluster CROSSSLOT errors occur when a multi-key command targets keys whose CRC16 hash slots differ, which the cluster forbids by design. This guide explains how to identify the offending keys, confirm the slot mismatch, and choose between hash tags, client-side grouping, or pipeline splitting as the corrective path.
Open guide →Redis MISCONF: diagnose persistence failure before changing eviction
Redis errors that begin with "MISCONF" are not memory pressure signals; they are the persistence subsystem telling the server that its durability guarantees can no longer be honored. Before any operator changes `maxmemory-policy` or raises memory limits, the persistence failure itself must be diagnosed, because disabling eviction pressure only masks the underlying safety policy violation that triggered the write refusal. This guide frames the diagnostic as a sequence: confirm the exact MISCONF error, prove that the disk and filesystem layer is the boundary that failed, then decide whether persistence should be repaired, temporarily relaxed, or reconfigured.
Open guide →Redis READONLY error: prove which endpoint accepted the write
When a Redis client receives a "READONLY You can't write against a read only replica" error, the immediate task is to prove which endpoint actually accepted the write attempt. The cause is almost always a misrouted client that landed on a replica, a Sentinel or Cluster client that did not refresh its topology after a failover, or a proxy layer that silently downgraded the connection. This guide walks through the evidence required to attribute the write to a specific endpoint before any code or configuration change is attempted.
Open guide →Spring ApplicationContextException: isolate startup infrastructure failure
Spring ApplicationContextException indicates that the Spring Boot application context failed to start a required infrastructure component (DataSource, JPA EntityManagerFactory, embedded web server, MessageSource, scheduling TaskScheduler, etc.). This guide focuses on isolating which dependency or bean blocked refresh, separating infrastructure failure from ordinary bean wiring errors.
Open guide →Spring NoSuchBeanDefinitionException: trace the missing bean contract
Spring NoSuchBeanDefinitionException indicates the ApplicationContext could not resolve a required bean by type or qualifier during dependency injection. This guide maps the exception's nested detail message to concrete configuration boundaries—component scanning, explicit @Bean declarations, conditional annotations, and proxy generation—so engineers can trace the missing bean contract rather than guess at the cause.
Open guide →Turborepo cache miss: determine whether inputs or environment changed
Diagnose Turborepo cache misses by separating input-graph changes from environment drift, using the task's hash metadata and Turbo's own logging to isolate whether files, env vars, dependencies, or daemon state invalidated the entry.
Open guide →TypeScript JSX element type error: inspect the component contract
A playbook for diagnosing the TypeScript "JSX element type" error when a value cannot be used as a component under the active type definitions. The guide frames the failure as a contract mismatch between the imported value, the JSX namespace, and tsconfig options such as jsx, jsxImportSource, and module resolution. It sequences triage from the compiler message through declaration lookup, generic constraints, and intrinsic vs component type checks.
Open guide →TypeScript type not assignable: reduce the incompatible value shape
A targeted playbook for resolving the TypeScript diagnostic "Type X is not assignable to type Y" when the failure stems from a value whose static shape (fields, optionality, generics, union membership, or index signature) does not satisfy the declared target type, rather than from a missing import or runtime mismatch.
Open guide →Vite failed to resolve import: find the graph edge that broke
A focused playbook for resolving Vite's "failed to resolve import" errors by tracing the import graph edge that broke. It sequences triage steps from the literal error string to targeted file-system and configuration checks, with decision points that separate missing files, missing extensions, alias/path misconfiguration, package export problems, and dependency-installation issues. Read-only commands and named evidence gates let engineers act without making blind edits.
Open guide →Vite optimized dependency mismatch: explain a stale prebundle
When Vite surfaces a "Pre-transform error" or "Outdated optimize dep" notification, the dev server is serving a prebundled dependency cache whose hash no longer matches the resolved module graph on disk. This guide explains how to recognize that exact mismatch, distinguish it from a real source error, and rebuild the cache with verifiable proof.
Open guide →Docker bind address already in use: trace the port owner
Docker's "bind: address already in use" appears when a published container port cannot bind because another process already owns that host socket. Trace the conflicting listener, decide whether to change the host port or stop the owner, then verify with a fresh container run.
Open guide →GitHub Actions permission denied: inspect the execution boundary
When a CI job fails with a permission error, the boundary to inspect is whether the token or runner process actually carries the rights the step assumes. This guide separates token-level authorization (GITHUB_TOKEN, PAT, OIDC) from runner-level capability (filesystem, network, self-hosted restrictions) using only log and configuration evidence.
Open guide →Java NullPointerException: identify the first invalid value
Practical debugging guide for Java NullPointerException, focused on locating the first invalid null reference along a call path. Begins from the thrown stack frame, walks outward through receivers, parameters, and return values, and shows how to prove the fix without speculative rewrites.
Open guide →Node.js EADDRINUSE: diagnose an address already in use error
EADDRINUSE is raised by Node.js when the underlying socket layer (libuv → OS) refuses a bind() call because the requested address and port tuple is already owned by another socket, often a stale process from a prior run, a hot-reload worker, or a colliding service on a shared host. The guide walks through identifying the holder, deciding whether to free the port or move to an alternative, and proving the new bind succeeds under the same conditions that originally failed.
Open guide →Node.js ERR_MODULE_NOT_FOUND: trace the missing module
This guide explains how to diagnose Node.js ERR_MODULE_NOT_FOUND, the error thrown when the runtime cannot resolve an imported package or file. It walks from the error message and stack trace through module resolution, package export maps, and filesystem checks, ending with safe fixes and proof-of-fix steps.
Open guide →PostgreSQL deadlock detected: read the lock graph
PostgreSQL raises 'deadlock detected' (SQLSTATE 40P01) when the deadlock detector finds a cycle of blocked transactions. This guide shows engineers how to read the lock graph from catalog views, identify the conflicting transactions, and decide whether the fix belongs in application logic or schema design.
Open guide →PostgreSQL too many connections: locate pool exhaustion
PostgreSQL "too many connections" / FATAL: remaining connection slots are reserved errors mean the server reached max_connections before client work could start. This guide helps backend engineers locate pool exhaustion by distinguishing server-side limits from application-side pool misconfiguration, using pg_stat_activity, reserved slots, and per-database/user limits as evidence.
Open guide →Python ModuleNotFoundError: find the environment mismatch
ModuleNotFoundError means the active Python interpreter resolved an `import` statement but could not locate the named module or its parent package. This guide walks through environment-mismatch causes — wrong interpreter, misaligned virtualenv, missing install, sys.path gaps — and shows how to verify which interpreter pip wrote to before changing anything.
Open guide →Redis WRONGTYPE: find the key contract violation
WRONGTYPE means a Redis command was issued against a key whose stored data type does not match the command's expected type. The fix is to identify the key, confirm its actual stored type, and resolve the contract mismatch by aligning the operation, the namespace, or the application code with the canonical type.
Open guide →TypeScript cannot find module: separate types from runtime resolution
Debug TypeScript's "cannot find module" error (often TS2307) by separating the type-checker's resolution from runtime (Node, bundler) resolution. Inspect the active tsconfig, confirm package type metadata, and verify each change before touching paths or moduleResolution.
Open guide →