Debugging Guides
Distinguish symptoms from root causes, then verify the fix.
697 published
Page 1 of 7
bcrypt Salt Rounds Too Low — Weak Hash
Diagnose security weakness from bcrypt salt rounds below 10, making hashes vulnerable to GPU brute-force attacks.
Cookie SameSite=None Requires Secure
Diagnose cookies being rejected when SameSite=None is set without the Secure attribute in modern browsers.
CORS Preflight Failed — OPTIONS Rejected
Diagnose CORS errors when the browser preflight OPTIONS request is rejected by the server missing Access-Control-Allow-Headers.
CSP Violation — Inline Script Blocked
Diagnose Content Security Policy violations where inline scripts or disallowed sources are blocked by the browser.
Fetch AbortController — Signal Already Aborted
Diagnose AbortError when a fetch signal is aborted before or during the request, and how to distinguish it from real errors.
History API State Lost — PushState Not Persisted
Diagnose SPA navigation state loss when history.pushState state is null or not restored on popstate.
IndexedDB Quota Exceeded — Storage Full
Diagnose QuotaExceededError when IndexedDB writes exceed the browser storage quota (typically 50% of disk).
Intl NumberFormat Locale Mismatch — Wrong Grouping
Diagnose wrong number formatting when Intl.NumberFormat uses a locale that does not match the user expectation.
ES Module Script CORS — Wrong MIME Type
Diagnose refused to execute module script because the server returns a wrong MIME type instead of text/javascript.
Performance Long Task — Main Thread Jank
Diagnose UI jank from long tasks (>50ms) on the main thread using PerformanceObserver and Long Task API.
requestAnimationFrame Throttled in Background Tab
Diagnose requestAnimationFrame being throttled to ~1fps in background tabs, causing animations or polling to stall.
ResizeObserver Loop — Completed With Undelivered
Diagnose ResizeObserver loop limit exceeded errors when observations trigger layout changes that cause a feedback loop.
Service Worker Update Not Triggered — Stale Cache
Diagnose a service worker not updating because the browser caches the sw.js file or skipWaiting is not called.
Shadow DOM Style Piercing — Custom Property Inheritance
Diagnose styles not applying inside shadow DOM because CSS custom properties inherit but regular selectors do not pierce.
WebGL Context Lost — GPU Reset
Diagnose WebGL context loss when the GPU resets or too many contexts are active, causing rendering to stop.
WebSocket Connection Timeout — Handshake Stalled
Diagnose WebSocket connections that never open because the handshake stalls or the server does not respond to the upgrade.
Docker Build Cache Miss — Slow Rebuilds
Diagnose Docker build cache misses from layer ordering where COPY of frequently-changed files precedes expensive RUN steps.
esbuild Target Mismatch — Unsupported Syntax
Diagnose esbuild errors when the target environment does not support syntax like top-level await or optional chaining.
ESLint Rule Conflict — Extends Overrides
Diagnose ESLint rule conflicts where one config extends another that sets contradictory rules (e.g., semi: always vs never).
Git Merge Conflict Unresolved — CI Fails
Diagnose CI build failures from unresolved git merge conflicts leaving conflict markers (<<<<<<<) in source files.
GitHub Actions Matrix Empty — No Jobs Run
Diagnose GitHub Actions workflows that produce an empty matrix, causing zero jobs to run with no error.
npm Peer Dependency Conflict — ERESOLVE
Diagnose npm ERESOLVE errors when peer dependency version ranges conflict across installed packages.
pnpm Hoisting — Peer Dep Not Found
Diagnose pnpm strict node_modules layout causing peer dependency not found errors that npm's flat layout would hide.
Terraform State Lock — Already Acquired
Diagnose Terraform errors when the state lock is held by another run, preventing concurrent apply operations.
Vite HMR Update Not Applied — Stale Module
Diagnose Vite HMR not applying updates because a module does not accept its own update or has side effects on import.
Webpack Module Not Found — Can't Resolve
Diagnose Module not found: Error: Can't resolve "X" in webpack from missing dependency or wrong extension.
CORS Credentials with Wildcard Origin — Rejected
Diagnose browsers rejecting credentialed CORS requests when Access-Control-Allow-Origin is set to wildcard "*".
CSP Report-Only vs Enforced — Violation Not Blocked
Diagnose CSP violations not being blocked because the policy is deployed in Content-Security-Policy-Report-Only mode.
CSRF Token Missing — SameSite Not Set
Diagnose CSRF vulnerabilities where state-changing requests lack a CSRF token and cookies do not have SameSite protection.
Go Context Deadline Exceeded — Timeout
Diagnose context.DeadlineExceeded when a context with timeout expires before the operation completes in Go.
Go Data Race Detected — Concurrent Map Write
Diagnose fatal error: concurrent map writes or WARNING: DATA RACE when multiple goroutines access a map without synchronization.
Go Goroutine Leak — Blocked on Channel Send
Diagnose goroutine leaks where a goroutine blocks forever on a channel send/receive because no receiver/sender exists.
Go Interface Conversion — Type Assertion Panic
Diagnose panic: interface conversion when a type assertion fails because the underlying type does not match in Go.
Go Nil Pointer Dereference — Runtime Panic
Diagnose panic: runtime error: invalid memory address or nil pointer dereference when dereferencing an uninitialized pointer in Go.
Array.sort Not Sorting Numbers — Default String Compare
Diagnose why Array.sort() produces wrong order for numbers because the default comparator converts elements to strings.
Async Function Not Awaited — Promise Lost
Diagnose bugs where an async function is called without await, causing the caller to proceed before the async work completes.
Cannot Read Property of Undefined — Silent Null Chain
Diagnose TypeError: Cannot read properties of undefined when accessing nested object properties without optional chaining or null guards.
Circular JSON.stringify — Converting Circular Structure
Diagnose TypeError: Converting circular structure to JSON when JSON.stringify encounters a self-referencing object.
Date Timezone Offset Bug — UTC vs Local Mix-up
Diagnose date off-by-one or wrong-hour bugs caused by mixing UTC methods (getUTCHours) with local methods (getHours) on Date objects.
Event Loop Starvation — Blocking Sync Work
Diagnose event loop starvation where a long synchronous computation blocks all I/O, timers, and async callbacks from executing.
Map vs Object Key Collision — Object Key Coercion
Diagnose bugs where Object keys are coerced to strings (1 becomes "1") while Map preserves key types, causing lookup mismatches.
Maximum Call Stack Size Exceeded — Infinite Recursion
Diagnose RangeError: Maximum call stack size exceeded caused by infinite recursion, missing base case, or mutual recursive cycles.
Memory Leak via Closures — Unintentional Retention
Diagnose memory leaks where closures unintentionally retain large objects, preventing garbage collection even after they are unused.
Number.isNaN vs Global isNaN — Type Coercion Difference
Diagnose bugs where global isNaN returns true for non-number values (isNaN("abc")) while Number.isNaN returns false, causing logic errors.
Floating Point Precision — 0.1 + 0.2 !== 0.3
Diagnose floating point arithmetic errors where 0.1 + 0.2 returns 0.30000000000000004 due to IEEE 754 binary representation.
Promise Pending Forever — Never Resolves
Diagnose a Promise that never settles because the resolve/reject callback is never invoked or is lost in a code path.
Proxy Reflect Invariant Violation — Get Trap Mismatch
Diagnose TypeError: Proxy invariant violation when a Proxy get trap returns a value inconsistent with the target property descriptor.
RegEx Catastrophic Backtracking — ReDoS Hang
Diagnose RegExp catastrophic backtracking (ReDoS) where a regex hangs on crafted input due to exponential backtracking paths.
StructuredClone Fails — Non-Cloneable Value
Diagnose DataCloneError when structuredClone encounters functions, DOM nodes, or class instances with non-cloneable internal slots.
Symbol Property Not Enumerable — JSON Misses It
Diagnose why Symbol-keyed properties are missing from JSON.stringify and for-in loops because Symbols are non-enumerable by design.
Temporal Dead Zone — Accessing Let/Const Before Init
Diagnose ReferenceError: Cannot access x before initialization when using a let/const variable before its declaration in the same scope.
TypeError: x Is Not a Function — Wrong Call
Diagnose TypeError: x is not a function when calling a non-callable value, a misnamed import, or a shadowed method.
Unhandled Promise Rejection — Missing Catch
Diagnose UnhandledPromiseRejection caused by an async function rejecting without a .catch() or try/await/catch handler.
WeakRef Dereferenced After GC — Undefined Target
Diagnose WeakRef.deref() returning undefined because the target was garbage collected between creation and dereference.
JWT Expired or Signature Invalid — 401
Diagnose 401 Unauthorized from JWT verification when the token is expired or the signature does not match the secret.
K8s ConfigMap Mounted But Not Updated
Diagnose pods not picking up ConfigMap changes because volume-mounted ConfigMaps are cached and require a pod restart or fsnotify.
K8s CrashLoopBackOff — Container Exit Code 1
Diagnose Kubernetes CrashLoopBackOff when a container exits with code 1 and Kubernetes restarts it in an exponential backoff.
K8s ImagePullBackOff — Registry Auth Missing
Diagnose ImagePullBackOff when Kubernetes cannot pull an image from a private registry due to missing imagePullSecrets.
K8s Ingress Path Not Routing — 404
Diagnose Ingress returning 404 because the pathType or path does not match the request, or the backend Service has no endpoints.
K8s Liveness Probe Failing — Pod Restarted
Diagnose pods being restarted because the liveness probe fails due to slow startup or wrong endpoint.
K8s OOMKilled — Container Memory Limit Exceeded
Diagnose OOMKilled pod termination when the container exceeds its memory limit and the kernel OOM killer invokes.
K8s Pod Pending — No Node Matches Scheduling
Diagnose pods stuck in Pending because no node has sufficient resources, tolerations, or node selector match.
K8s PVC Pending — No Storage Class
Diagnose PersistentVolumeClaim stuck in Pending because the storage class does not exist or no dynamic provisioner is configured.
K8s RBAC Forbidden — Cluster Role Binding Missing
Diagnose 403 Forbidden errors when a service account lacks the cluster role binding needed for an operation.
K8s Service No Endpoints — Pod Not Ready
Diagnose a Kubernetes Service with no endpoints because pods are not ready or readiness probe fails.
Node new Buffer() Deprecation — Unsafe Allocation
Diagnose deprecation warnings from new Buffer() which can leak sensitive memory; use Buffer.alloc or Buffer.from instead.
Node CJS vs ESM — __dirname Not Defined
Diagnose __dirname and __filename being undefined in ES modules because they are CommonJS-only globals.
Node Cluster Shared State Not Shared — Fork Isolation
Diagnose bugs where Node cluster workers have separate memory, so in-memory state like counters and caches are not shared.
Node EADDRINUSE — Port Already in Use
Diagnose Error: listen EADDRINUSE when starting a Node server because the port is already bound by another process.
Node EMFILE — Too Many Open Files
Diagnose Error: EMFILE when Node exceeds the OS file descriptor limit due to unclosed handles or bulk file operations.
Node EPIPE — Broken Pipe in Stream
Diagnose Error: EPIPE when writing to a stream whose consumer has closed the pipe, causing unhandled stream errors.
Node EventEmitter Max Listeners — Leak Warning
Diagnose MaxListenersExceededWarning when adding more than 10 listeners to an EventEmitter without removing old ones.
Node fs Callback Deferred — I/O Starvation
Diagnose fs callback starvation when the event loop is blocked by microtasks (process.nextTick) delaying I/O callbacks.
Node Heap Out of Memory — V8 Limit Exceeded
Diagnose FATAL ERROR: Ineffective mark-compacts when V8 heap exceeds the default 1.5 GB limit on large data processing.
Node path.join Platform Separator — Windows vs POSIX
Diagnose path joining producing wrong separators when using path.posix on Windows or path.win32 on Linux, or vice versa.
Node Pipe Error Unhandled — Destination Crash
Diagnose crashes when a piped destination stream errors and the source has no error handler, crashing the process.
Node process.exit Before Stream Finish — Data Lost
Diagnose truncated output when process.exit() is called before async writes (stdout, file streams) have flushed.
Node Require in ESM — Cannot Use require
Diagnose Error: require is not defined when using CommonJS require() inside an ES module (.mjs or type: module).
Node setImmediate vs process.nextTick — Ordering Surprise
Diagnose callback ordering bugs from mixing process.nextTick (microtask) and setImmediate (check phase) with different priorities.
Node Stream Backpressure Ignored — Memory Bloat
Diagnose memory bloat when a writable stream cannot keep up but the producer ignores backpressure and keeps calling write.
Node Stream Error Not Propagated — Silent Failure
Diagnose stream errors that are silently swallowed because no "error" listener is attached, causing pipelines to hang.
Node TLS Cert Rejected — Self-Signed Certificate
Diagnose UNABLE_TO_VERIFY_LEAF_SIGNATURE or SELF_SIGNED_CERT_IN_CHAIN when connecting to a server with a self-signed certificate.
Node uncaughtException — Process Exits Ungracefully
Diagnose process crashes from uncaught exceptions without proper handlers, leaving connections and data in inconsistent state.
Node URL WHATWG vs Legacy — Parsing Difference
Diagnose URL parsing differences between the legacy url.parse() and the WHATWG URL constructor, causing wrong pathname or search.
Node Worker Thread MessagePort Closed — Send After Close
Diagnose Error: MessagePort closed when posting a message to a Worker whose port has been terminated or garbage collected.
OAuth State Mismatch — CSRF Protection
Diagnose OAuth state parameter mismatch errors that indicate a CSRF attack or lost session state.
Password Hash Timing Attack — Non-Constant Compare
Diagnose timing attack vulnerabilities where password or hash comparison uses === instead of a constant-time comparison.
Python AttributeError — Module Has No Attribute
Diagnose AttributeError: module has no attribute when accessing a name that was not imported or was shadowed.
Python AttributeError — None Has No Attribute
Diagnose AttributeError: NoneType object has no attribute when a function returns None unexpectedly and the caller chains a method.
Python DeprecationWarning — Pandas Chained Indexing
Diagnose DeprecationWarning or SettingWithCopyWarning from chained indexing in pandas like df[df.a>0]["b"] = 1.
Python ImportError — Circular Import Detected
Diagnose ImportError from circular imports where module A imports B and B imports A, causing partial initialization.
Python KeyError — Dict Missing Key
Diagnose KeyError when accessing a dict key that does not exist, and compare dict[] vs dict.get() for safe access.
Python ModuleNotFoundError — No Module Named
Diagnose ModuleNotFoundError when Python cannot find an installed package due to wrong interpreter, venv, or PYTHONPATH.
Python OSError — File Locked on Windows
Diagnose PermissionError/OSError when a file is locked by another process on Windows, preventing open or delete.
Python pickle.UnpicklingError — Class Not Found
Diagnose pickle.UnpicklingError when unpickling an object whose class has been moved or renamed since pickling.
Python RecursionError — Maximum Recursion Depth
Diagnose RecursionError: maximum recursion depth exceeded from infinite recursion or a missing base case in Python.
Python RuntimeError — Async Event Loop Already Running
Diagnose RuntimeError: This event loop is already running when calling asyncio.run inside an already-running loop.
Python SyntaxError — F-String Backslash Not Allowed
Diagnose SyntaxError when using backslashes inside f-string expressions, which was disallowed before Python 3.12.
Python TypeError — Unhashable Type: List
Diagnose TypeError: unhashable type: list when using a list as a dict key or set element, which requires hashable types.
Python UnicodeEncodeError — Codec Cannot Encode
Diagnose UnicodeEncodeError when writing a Unicode string to a stream that uses a limited encoding like ASCII or cp1252.