Debugging Guides
Distinguish symptoms from root causes, then verify the fix.
697 published
Page 7 of 7
Vite — WebSocket connection failed for HMR behind a proxy
Fix Vite HMR websocket failures by configuring the dev server host, port and proxy for the environment.
Webhooks — HMAC Signature Validation Fails After No Code Change
Fix webhook signature verification failures caused by body parsing order, encoding, and timestamp tolerance, and compare digests in constant time.
webpack — Module parse failed: Unexpected token
Fix webpack parse failures by adding the right loader for the file type and excluding build artifacts from rule matching.
WebSocket — close code 1001 going away disconnects clients
Diagnose WebSocket 1001 closures by identifying scheduled restarts, idle proxies and deployment churn.
C# NullReferenceException — Enable Nullable and Find the Null
Diagnose C# NullReferenceException by reading the stack trace, enabling nullable reference types, and fixing uninitialized dependencies, LINQ defaults, and async results.
DNS SERVFAIL — DNSSEC, Delegation, and Resolver Failures
Diagnose DNS SERVFAIL by comparing resolvers, checking the authoritative servers, validating DNSSEC with delv, and fixing delegation or zone-signing problems.
Docker build context too large — Speed Up Builds with .dockerignore
Diagnose oversized Docker build contexts by measuring directory size and transfer output, then exclude node_modules, .git, and artifacts with .dockerignore.
Docker Hub pull rate limit — toomanyrequests in CI and Kubernetes
Diagnose Docker Hub rate limit errors by checking the pull token and rate limit headers, then authenticate, mirror, and cache images to keep CI and clusters pulling.
Docker Permission Denied — Cannot Connect to the Daemon Socket
Fix permission denied on /var/run/docker.sock by checking group membership, socket ownership, Docker context, and rootless daemon paths before relaxing permissions.
Elasticsearch yellow cluster — Unassigned Replica Shards Explained
Diagnose Elasticsearch yellow cluster health by inspecting unassigned replicas, allocation explain output, disk watermarks, and node roles before adding capacity.
Git LFS pointer file — Why the Binary Is Just Text
Diagnose Git LFS pointer files by checking filters, attributes, and lfs status, then install hooks, pull objects, or migrate files committed without LFS.
Git merge conflict — Resolve Markers Without Losing Changes
Diagnose and resolve Git merge conflicts by listing unmerged paths, reading both sides, choosing a semantic resolution, and verifying with tests before committing.
GitHub Actions Cache Miss — Why the Cache Never Restores
Diagnose GitHub Actions cache misses caused by unstable keys, branch scoping, and eviction, then design a key and restore-keys strategy that actually hits.
Go Deadlock — all goroutines are asleep
Diagnose Go deadlocks from channel sends, WaitGroup misuse, and lock ordering by reading goroutine dumps from SIGQUIT, test timeouts, and pprof profiles.
Go HTTP client timeout — context deadline exceeded Explained
Diagnose Go HTTP timeouts by measuring connect, TLS, and first-byte latency, then setting client, transport, and context deadlines that match real upstream behavior.
Go slice bounds out of range — Off-by-One and Capacity Traps
Diagnose Go slice bounds panics by reading the reported index and capacity, checking len versus cap, and adding explicit guards and edge-case tests.
HAProxy 503 no server available — Fix Failed Backend Health Checks
Diagnose HAProxy 503 errors by reading the runtime stats socket, identifying DOWN servers and check failures, then correcting health check probes and timeouts.
Java ClassNotFoundException — Missing Class on the Runtime Classpath
Trace ClassNotFoundException from packaging to runtime classpath by inspecting the jar, dependency tree, and class loader instead of adding random libraries.
Java deadlock — Read jstack and Fix Lock Ordering
Diagnose Java deadlocks by capturing a jstack thread dump, reading the deadlock report and lock owners, then enforcing a global lock order or using tryLock timeouts.
Java GC overhead limit exceeded — Find the Allocation Pressure
Diagnose GC overhead limit errors with jstat, heap histograms, and GC logs, then fix leaks and allocation hotspots before increasing the heap.
Jest did not exit — Find and Fix Open Handles
Diagnose Jest hanging after tests by running detectOpenHandles, identifying servers, timers, and database clients left open, then closing them in afterAll hooks.
JWT invalid signature — Secret, Algorithm, and Key Rotation
Diagnose JWT invalid signature errors by decoding the header, verifying with the correct algorithm and key, checking kid rotation, and reproducing the exact bytes.
Kafka Consumer Lag — Find Stuck Partitions and Rebalance Storms
Diagnose growing Kafka consumer group lag with consumer-group tooling, partition counts, poll interval limits, and processing time measurements before adding consumers.
Kafka producer TimeoutException — Expiring Records in Batch
Diagnose Kafka producer timeouts by checking topic metadata, ISR health, and delivery timeout budgets, then fix acks, linger, retries, and broker capacity.
Kafka rebalance storm — Why Consumer Groups Keep Rebalancing
Diagnose Kafka rebalance storms by reading coordinator logs and consumer group generation changes, then tune poll intervals, batch sizes, and static membership.
Kubernetes Evicted Pod — Node Pressure and Ephemeral Storage
Diagnose Kubernetes pod evictions by reading eviction messages and node pressure conditions, then fix resource requests, ephemeral storage limits, and kubelet GC.
Kubernetes Pending Pod — Schedule Failures and PVC Binding
Diagnose Kubernetes Pending pods by reading scheduler events, node allocatable resources, taints, affinity rules, and PVC binding, then correct the manifest.
Kubernetes readiness probe failing — Running but Never Ready
Diagnose Kubernetes readiness probe failures by testing the probe endpoint inside the pod, reviewing probe timing and app dependencies, then fixing startup and health routes.
Linux disk full — No Space Left on Device With Free Space
Diagnose Linux disk-full errors by checking blocks and inodes, finding deleted-but-open files, and locating log or container growth before cleaning safely.
Linux OOM killer — Identify the Killed Process and Prevent It
Diagnose Linux OOM kills with dmesg and journalctl, identify the victim and cgroup limit, then fix leaks, concurrency, and memory sizing instead of disabling overcommit.
Linux Too Many Open Files — Find the Leaking File Descriptor
Resolve EMFILE and Too many open files errors by counting descriptors per process, identifying the leaked resource, and sizing systemd and kernel limits correctly.
MongoDB slow query — Use the Profiler and explain() to Find It
Diagnose MongoDB slow queries with the database profiler and executionStats, then fix collection scans, missing indexes, and oversized result sets.
MySQL ERROR 1040 Too many connections — Diagnose and Fix
Diagnose MySQL ERROR 1040 by measuring Threads_connected against max_connections, inspecting processlist sleepers, then fixing leaks, wait_timeout, and pool sizing.
Nginx 502 Bad Gateway — Upstream Connection Refused or Closed
Diagnose nginx 502 errors by reading the error log, testing the upstream directly, and checking listener addresses, timeouts, and proxy protocol settings.
nginx 504 — Upstream Timed Out While Reading Response Headers
Diagnose nginx 504 upstream timed out errors by measuring the backend directly, checking proxy timeouts and buffering, and fixing slow handlers before raising limits.
Node.js ECONNRESET — Keep-Alive Socket Closed by the Server
Fix read ECONNRESET and socket hang up in Node.js by tracing reused keep-alive sockets, aligning agent and server timeouts, and retrying only idempotent requests.
npm ERESOLVE peer dependency conflict — Resolve Without --force
Diagnose npm ERESOLVE errors with npm ls, npm explain, and peerDependencies metadata, then align versions or use targeted overrides instead of disabling peer checks.
PHP Fatal error — Undefined Function and Class Not Found
Diagnose PHP fatal errors by linting the file, reproducing with full error reporting, checking extensions and autoloading, then fixing namespaces and composer class maps.
Playwright test timeout — Debug Locator and Navigation Waits
Diagnose Playwright timeouts with traces, headed debugging, and single-worker runs, then replace fixed sleeps with web-first assertions and stable locators.
pnpm ERR_PNPM_OUTDATED_LOCKFILE — Fix Frozen Lockfile Failures
Diagnose pnpm frozen-lockfile failures by comparing package.json with pnpm-lock.yaml, aligning the pnpm version, and regenerating and committing the lockfile.
PostgreSQL Connection Reset — Server Closed the Connection Unexpectedly
Diagnose PostgreSQL connection resets after idle periods by comparing backend logs, idle session age, and infrastructure timeouts, then fix keepalive and pool lifetime.
PostgreSQL no pg_hba.conf entry — Fix Host-Based Authentication
Diagnose PostgreSQL FATAL: no pg_hba.conf entry errors by reading pg_hba_file_rules, matching client address and SSL mode, then adding and reloading a host rule.
PostgreSQL idle in transaction — Long Sessions Holding Locks
Find PostgreSQL sessions stuck in idle in transaction, measure how long they hold locks and snapshots, then enforce transaction timeouts and fix application boundaries.
Python asyncio timeout — TimeoutError, Blocked Loop, and Slow Tasks
Diagnose asyncio timeouts by timing coroutines, finding blocking calls, checking downstream latency and concurrency limits, then applying explicit timeout budgets.
Python ModuleNotFoundError and circular ImportError — Fix Imports
Diagnose Python import failures by checking sys.executable and sys.path, finding shadowing modules and circular imports, then installing into the active environment.
Python CERTIFICATE_VERIFY_FAILED — Trust Store and CA Bundle Fixes
Fix Python SSL certificate verification failures by auditing the CA bundle, corporate interception, environment overrides, and clock skew without disabling verification.
RabbitMQ queue backlog — Find the Bottleneck Behind Growing Depth
Diagnose RabbitMQ queue backlog by comparing ready, unacknowledged, and consumer counts, then fix slow consumers, prefetch, requeue loops, and memory alarms.
Redis MOVED redirect — Fix Cluster Slot Routing Errors
Diagnose Redis cluster MOVED errors by checking slot ownership, node announcements, and client topology refresh, then configure a cluster-aware client correctly.
Redis Command Timeout — Separate Slow Commands from Network Delays
Track down Redis client timeouts by separating blocking commands from network and pool problems using SLOWLOG, latency probes, and INFO statistics instead of raising timeouts.
Ruby LoadError cannot load such file — Bundler and Gems Explained
Diagnose Ruby LoadError by running through bundle exec, checking bundle check and the load path, then fixing missing gems, platform locks, and native extensions.
Rust E0382 borrow of moved value — Ownership Fixes That Compile
Diagnose Rust move and borrow errors by reading the compiler's move trace, then choose borrowing, cloning, split borrows, or mem::take deliberately.
Cargo Lock Conflict — Failed to Select a Version for the Requirement
Resolve Cargo version selection and lockfile conflicts by inspecting the dependency tree, aligning semver requirements, and regenerating Cargo.lock in the right place.
TLS handshake failure — Certificate, SNI, and Cipher Mismatch
Diagnose TLS handshake failures with openssl s_client and curl verbose output, checking certificate chains, SNI virtual hosts, protocol versions, and client trust.
Vite optimize deps — Missing Exports and Reload Loops
Diagnose Vite dependency pre-bundling problems by clearing the cache, reading optimize debug output, and configuring include, exclude, and dedupe for linked packages.
Webpack JavaScript heap out of memory — Production Build OOM Fix
Diagnose webpack heap exhaustion by measuring build memory and stats, then raise Node's heap, disable heavy source maps, split chunks, and reduce module graph size.
WebSocket 1006 abnormal closure — Proxy Upgrade and Idle Timeouts
Diagnose WebSocket 1006 errors by checking the handshake response, proxy Upgrade headers, idle timeouts, and server crashes, then add heartbeats and clean reconnects.
CSS — z-index has no effect
Diagnose z-index failures caused by stacking contexts, parent stacking order, and transform or opacity, then fix the layout instead of escalating numbers.
Docker Compose — depends_on does not wait for readiness
Fix startup races where an app starts before its database or queue is ready by adding healthchecks and condition-based dependencies, plus application retries.
Docker — exec format error on container start
Diagnose exec format errors caused by an arm64/amd64 image or binary mismatch, verify the platform digest, and build a multi-architecture image.
Docker — no space left on device
Diagnose Docker disk exhaustion from images, containers, volumes, build cache, logs, or inodes, and reclaim space without deleting active data.
Git — push rejected (non-fast-forward)
Diagnose a rejected Git push by comparing local and remote history, rebasing or merging deliberately, and avoiding destructive force-pushes on shared branches.
Go — context deadline exceeded
Find which deadline expired in a Go call chain, distinguish a caller timeout from a dependency timeout, and fix propagation instead of increasing timeouts blindly.
Go — data race detected by the race detector
Read a Go race report, identify the conflicting accesses, and fix the synchronization with a mutex, channel, or atomic rather than ignoring the warning.
Java — OutOfMemoryError: Java heap space
Diagnose a Java heap exhaustion with heap dumps, GC logs, and allocation analysis, and fix the leak or sizing instead of only raising -Xmx.
Kubernetes — CrashLoopBackOff
Diagnose CrashLoopBackOff from pod events, previous logs, and exit codes, then fix the application, probe, configuration, or resource limit that restarts the container.
Kubernetes — ImagePullBackOff
Diagnose ImagePullBackOff from pod events and registry authentication, covering wrong tags, missing pull secrets, architecture mismatches, and rate limits.
MySQL — Lock wait timeout exceeded
Diagnose MySQL lock waits from long transactions, missing indexes, or conflicting update order, and fix the wait instead of only raising the timeout.
Nginx — 413 Request Entity Too Large
Diagnose uploads rejected by Nginx with 413, align client_max_body_size across proxy and app, and return a clear JSON error without weakening limits.
Node.js — JavaScript heap out of memory
Diagnose a Node.js heap exhaustion by capturing a heap snapshot, finding retained objects, and fixing the leak instead of only raising the heap limit.
Node.js — Unhandled promise rejection
Find the promise that rejected without a handler, fix floating async calls and async event handlers, and add a process-level safety net without swallowing errors.
PHP — Allowed memory size exhausted
Diagnose PHP memory exhaustion by locating the peak allocation, fixing unbounded data loading, and raising memory_limit only with evidence.
PostgreSQL — deadlock detected
Diagnose PostgreSQL deadlocks by reading the server log, identifying conflicting lock order, shortening transactions, and adding bounded retries.
Python — RuntimeError: Event loop is closed
Trace an asyncio closed-loop error to repeated asyncio.run calls, closed clients, or test fixture scope, and fix the lifecycle instead of catching the error.
Python — KeyError on a Dictionary Lookup
Trace a Python KeyError to the missing key, distinguish an absent key from a None value, and choose between defaults, validation, and explicit errors.
Python — pip dependency conflict (ResolutionImpossible)
Diagnose pip resolver failures by tracing direct and transitive constraints, relaxing incompatible pins, and using constraints files instead of disabling dependencies.
Python — RecursionError: maximum recursion depth exceeded
Find the missing or unreachable base case, convert deep recursion to an explicit stack, and avoid raising the recursion limit as a substitute for a fix.
Redis — OOM command not allowed
Diagnose Redis memory exhaustion by checking maxmemory, eviction policy, large keys, and fragmentation, then choose capacity or eviction deliberately.
Rust — linking with cc failed
Diagnose Rust linker errors from missing native libraries, wrong target toolchains, feature flags, or duplicate symbols, and fix the build environment.
SQLite — database disk image is malformed
Diagnose SQLite corruption with integrity checks, preserve the file, recover data with .recover or a dump, and fix disk or lifecycle causes.
SQLite — database is locked
Diagnose SQLITE_BUSY errors by shortening write transactions, enabling WAL and a busy timeout, and avoiding long-lived read locks.
TypeScript — TS2345 Argument Type Not Assignable
Diagnose and fix TypeScript error TS2345 by reading the full type, narrowing unions, handling optional properties, and avoiding unsafe any casts.
Vite / Webpack — Module not found
Diagnose unresolved imports caused by case sensitivity, aliases, package exports, missing dependencies, or the wrong working directory, and fix resolution without disabling checks.
CORS Preflight Failed — Browser Blocks the Request
Diagnose preflight failures by inspecting the OPTIONS request and response headers, then fix origin, method, header, or credential configuration.
Docker — Port Is Already Allocated
Resolve Docker bind failures by identifying which container or host process already publishes the port, then changing or freeing the mapping without disrupting unrelated services.
Git Detached HEAD — Commits Not on a Branch
Recover from a detached HEAD by attaching a new or existing branch before switching away, so commits are not left unreachable.
Go — Nil Pointer Dereference Panic
Trace a nil pointer panic from the stack trace, find the unchecked nil value, and fix it with explicit error handling and regression tests.
HTTP 502 Bad Gateway — Proxy Cannot Reach the Upstream
Trace a 502 from the reverse proxy to the upstream service, distinguishing a down backend, a wrong address or port, a timeout, and an application crash.
JavaScript Maximum Call Stack Exceeded
Find unbounded recursion or circular traversal behind RangeError, then convert to iteration, add a base case, or break cycles with a visited set.
Node.js EADDRINUSE — Port Already in Use
Diagnose and resolve EADDRINUSE when a Node.js server cannot bind a port because another process is listening or a previous instance did not exit cleanly.
npm ERESOLVE — Peer Dependency Conflict
Resolve npm ERESOLVE errors by reading the dependency tree, aligning peer ranges, deduplicating versions, and using overrides only with a documented reason.
PostgreSQL — Too Many Connections
Diagnose connection exhaustion by measuring active, idle, and leaked sessions, then bound connection pools and release clients reliably.
Python ModuleNotFoundError — Wrong Interpreter or Missing Dependency
Diagnose ModuleNotFoundError by confirming which interpreter runs the code, which environment holds the package, and whether the import name differs from the package name.
React Hydration Mismatch — Server and Client HTML Differ
Diagnose hydration errors by finding non-deterministic render output, browser-only state, invalid HTML nesting, or locale differences between server and client.
Rust — Cannot Borrow as Mutable More Than Once
Resolve E0499 and E0502 by shortening borrow scopes, restructuring data ownership, or using interior mutability only when runtime checking is truly required.
Async Race Condition — Out-of-Order Responses
Diagnose and fix race conditions in concurrent async operations where later requests resolve before earlier ones, causing stale data to overwrite fresh results.
Browser Memory Leak — Detached DOM Nodes
Identify and fix memory leaks caused by references to removed DOM nodes that prevent garbage collection when event listeners, closures, or data caches maintain strong references.
React Infinite Render Loop — useState + useEffect Without Dependencies
Diagnose and fix infinite render loops caused by calling setState unconditionally inside useEffect without a dependency array.