Debugging Guides
Distinguish symptoms from root causes, then verify the fix.
697 published
Page 2 of 7
Rate Limit Redis Counter — Race Condition
Diagnose rate limit bypass when the Redis INCR + EXPIRE pattern has a race condition between increment and set-expire.
Rust Borrow Checker — Multiple Mutable Borrows
Diagnose Rust error E0499: cannot borrow as mutable more than once when two mutable references to the same value are alive.
Rust Integer Overflow Panic — Debug Mode Only
Diagnose Rust panic on integer overflow in debug mode that silently wraps in release mode, causing divergent behavior.
Rust Lifetime Mismatch — Reference Outlives Data
Diagnose Rust error E0597: borrowed value does not live long enough when a reference outlives the data it points to.
Rust Send/Sync Not Implemented — Cross-Thread Move
Diagnose Rust error E0277: trait Send (or Sync) not implemented when moving a non-Send type across thread boundaries.
Rust Unwrap Panic — Option Is None
Diagnose Rust panic: called Option::unwrap() on a None value when unwrap is called on an empty Option.
Secrets Leaked via env var in Logs
Diagnose secret leakage when environment variables containing API keys or tokens are logged by error handlers or debug output.
SQL Ambiguous Column Name — Join Needs Alias
Diagnose Error 1052: Column "id" in field list is ambiguous when joining tables with same column name without qualification.
SQL Connection Pool Exhausted — Timeout Acquiring
Diagnose TimeoutError or pool exhaustion when all database connections are in use and new queries wait indefinitely.
SQL Data Too Long for Column — Truncation Rejected
Diagnose Error 1406: Data too long for column when inserting a value exceeding the column width in strict mode.
SQL Deadlock Detected — Transaction Rolled Back
Diagnose Error 1213: Deadlock found when trying to get lock from two transactions waiting on each other in InnoDB.
SQL Division by Zero in Query
Diagnose NULL or error results from dividing by zero in SQL queries, and how to guard with NULLIF.
SQL Duplicate Entry — Unique Constraint Violation
Diagnose Error 1062: Duplicate entry when inserting a row that violates a unique or primary key constraint.
SQL Foreign Key Constraint Fails — Child Row
Diagnose Error 1452: Cannot add or update a child row when the referenced parent row does not exist.
SQL GROUP BY — ONLY_FULL_GROUP_BY Rejected
Diagnose Error 1055: Expression of SELECT list is not in GROUP BY when ONLY_FULL_GROUP_BY SQL mode is enabled.
SQL Incorrect Datetime Value — Invalid Format
Diagnose Error 1292: Incorrect datetime value when inserting a date in the wrong format or an invalid date like 2026-02-30.
SQL Index Not Used — Full Table Scan
Diagnose slow queries where an index exists but is not used due to function wrapping, type mismatch, or LIKE prefix wildcard.
SQL Injection — Unparameterized Query
Diagnose SQL injection vulnerabilities where user input is concatenated into SQL instead of using parameterized queries.
SQL Lock Wait Timeout Exceeded — 50s
Diagnose Error 1205: Lock wait timeout exceeded when a transaction waits too long for a row lock held by another transaction.
SQL Migration Alter Table Blocks — Long Lock
Diagnose table-level lock and downtime when ALTER TABLE modifies a large table without online DDL or pt-online-schema-change.
SQL NOT NULL Constraint Violation
Diagnose Error 1048: Column cannot be null when inserting NULL into a NOT NULL column.
SQL Prepared Statement Params Mismatch
Diagnose errors when the number of placeholders in a prepared statement does not match the bound parameters.
SQL InnoDB Deadlock — Gap Lock Conflict
Diagnose InnoDB deadlocks from gap locks under REPEATABLE READ when range scans lock gaps that conflict across transactions.
TLS Certificate Expired — Handshake Failure
Diagnose TLS handshake failures when the server certificate has expired, causing clients to refuse the connection.
TS Conditional Type Distributive — Unexpected Union
Diagnose TypeScript conditional types distributing over union inputs, producing an unexpected union of results instead of a single type.
TS Decorator Metadata Missing — reflect-metadata Not Loaded
Diagnose TypeScript decorator parameter types being undefined because reflect-metadata polyfill is not imported before decorator usage.
TS Enum vs Const Enum — Isolation Failure
Diagnose issues with const enum not being inlined across package boundaries, causing runtime ReferenceError in isolated modules.
TS Generic Constraint Too Loose — Unsafe Access
Diagnose TypeScript errors where a generic type parameter lacks a constraint, allowing unsafe property access that fails at runtime.
TS import type vs import — Runtime Value Missing
Diagnose runtime errors when using import type for a value that is needed at runtime, or vice versa, causing missing references.
TS Module Augmentation Not Applied — Declaration Merge
Diagnose TypeScript module augmentation failing to merge because the augmenting file is not loaded or the module path does not match.
TS Promise Type Not Awaited — Missing Await in Type
Diagnose TypeScript reporting Promise<T> instead of T because an async function return is not awaited in the type position.
TS satisfies vs Type Annotation — Narrowing Lost
Diagnose TypeScript narrowing differences between x: T = ... and x = ... satisfies T, where the latter preserves literal types for inference.
TS Strict Null Checks Off — Undefined Slips Through
Diagnose runtime undefined errors caused by strictNullChecks being disabled, allowing undefined to be used as a defined value.
TS Type Narrowing Failure — Union Not Narrowed
Diagnose TypeScript errors where type narrowing fails inside callbacks or after reassignment, leaving a union type instead of the narrowed subtype.
XSS via innerHTML — Sanitizer Bypass
Diagnose XSS vulnerabilities where user input is set via innerHTML and the sanitizer is bypassed by encoded or nested payloads.
Anthropic — context window exceeded error
Anthropic returns an error because the total input tokens plus requested max_tokens exceed the model context window, requiring truncation or a larger model.
Astro — content collection schema validation error
Astro build fails because a Markdown frontmatter field does not match the Zod schema defined in content.config.ts for the collection.
Astro — slot is undefined when rendering component
An Astro component throws "slot is not a function" or renders empty because the named slot was not passed or was misspelled in the parent template.
Azure Blob Storage — authentication failed with 403
Azure Blob Storage returns 403 because the SAS token expired, the storage key changed, or the managed identity lacks the Storage Blob Data Reader role.
Bun — module not found despite being installed
Bun fails to resolve a module that is listed in package.json and present in node_modules, often due to resolution strategy or conditional exports.
Cloudflare Workers — CPU time limit exceeded
A Cloudflare Worker throws "exceeded CPU limit" because the request consumed more CPU time than the plan allows, from a tight loop or heavy computation.
Cloudflare Wrangler — binding not found in Worker
A Cloudflare Worker throws "binding X does not exist" because the KV, R2, or D1 binding in code is not declared in wrangler.toml or the dashboard.
Consul — service registration failed with ACL denial
Consul rejects service registration because the agent token lacks the service:write ACL permission, or the ACL system is enabled without a valid token.
CSV — column count mismatch on parse
CSV parser throws a column count mismatch because a row has more or fewer fields than the header, often from unquoted commas or missing trailing delimiters.
Deno — permission denied for network or file access
Deno throws PermissionDenied because the script accesses a resource without the required --allow flag, unlike Node.js which grants permissions by default.
Drizzle ORM — column type mismatch on query
Drizzle ORM throws a type error or runtime error because the column type in the schema does not match the actual database column type or the query value.
Elasticsearch — high disk watermark blocks index allocation
Elasticsearch marks indices read-only because disk usage exceeds the high watermark, blocking writes to prevent corruption from a full disk.
etcd — lease expired before keepalive
etcd returns lease not found because the lease TTL expired before a keepalive was sent, causing attached keys to be deleted automatically.
Firebase Firestore — permission-denied on document access
Firestore returns permission-denied because the security rules do not allow the authenticated user to read or write the requested document or collection.
Google Cloud Storage — blob not found on download
GCS returns 404 Not Found because the blob name or bucket is incorrect, or the blob is in a different project or location.
gRPC — status 14 unavailable from server
gRPC returns status 14 UNAVAILABLE because the server is down, the connection was reset, or keepalive pings were not answered within the timeout.
JSON Schema — additionalProperties false rejects extra fields
JSON Schema validation fails because additionalProperties is set to false and the input contains fields not defined in the properties object.
Kafka — transaction timed out before commit
Kafka aborts a transaction because the producer did not commit or abort within the transaction timeout interval, leaving messages in an indeterminate state.
LangChain — chain input type mismatch error
LangChain throws a type error because a chain step receives input that does not match its expected schema, often after composing incompatible chains.
MinIO — bucket does not exist on put operation
MinIO returns NoSuchBucket because the target bucket was not created before the put operation, or the bucket name is misspelled or in a different region.
Next.js App Router — params not available in client component
A Next.js client component receives params as a Promise in App Router 15+ but uses it synchronously, causing "params is not a function" or undefined access.
Nuxt 3 — Nitro renderer not found for route
Nuxt 3 build fails because a route or page does not have a matching Nitro renderer, often after changing the rendering mode or nitro preset.
OpenAI — rate limit exceeded with 429 and retry-after
OpenAI returns 429 Too Many Requests because the request rate or token usage exceeds the account tier limit, with a retry-after header indicating when to retry.
OpenAPI — request validation failed against spec
An OpenAPI validator rejects a request because a parameter or body field does not match the schema defined in the specification for the path and method.
Prisma — migration shadow database schema mismatch
Prisma migration fails because the shadow database schema does not match the migration history, often after manual schema changes or drift between environments.
Protobuf — field number out of valid range
Protobuf compilation fails because a field number is 0, exceeds 536870911, or uses reserved numbers 19000-19999 that Protobuf reserves internally.
RabbitMQ — message TTL expired before consumption
RabbitMQ drops messages because the queue or message TTL expires before a consumer processes them, causing silent message loss under high load.
Redis Sentinel — quorum not met for failover
Redis Sentinel cannot failover because the number of available sentinels is less than the configured quorum, leaving the cluster without a new master.
AWS S3 — multipart upload stalled and never completed
An S3 multipart upload stalls because individual parts time out or the network drops, leaving an incomplete upload that incurs storage costs until aborted.
SendGrid — API key unauthorized with 403
SendGrid returns 403 Forbidden because the API key lacks the required scope or belongs to a different team or subuser, despite being valid.
Stripe — idempotency key causes stale response
Stripe returns a stale response because the same idempotency key is reused with different request bodies, so the first response is returned for later calls.
Supabase — RLS policy blocks insert with 42501
Supabase returns 42501 on insert because Row Level Security is enabled but no policy allows the authenticated user to insert into the table.
SvelteKit — form action blocked by CSRF check
SvelteKit rejects a form submission with 403 Forbidden because the origin header does not match the app origin, triggering the built-in CSRF protection.
Tailwind CSS — classes missing from production build
Tailwind CSS purges classes that are dynamically constructed or in files outside the content configuration, causing missing styles in production but not in dev.
TOML — type mismatch error during parse
TOML parser throws a type mismatch because a value is assigned to a key that was previously declared with a different type, which TOML strictly prohibits.
Twilio — request signature validation failed for webhook
Twilio webhook handler rejects the request because the X-Twilio-Signature header does not match the expected HMAC computed from the auth token and URL.
Vercel — serverless function exceeds size limit
Vercel build fails because a serverless function bundle exceeds the 250 MB uncompressed size limit, often from large dependencies or missing edge configuration.
XML — XXE entity expansion attack blocked
XML parser rejects an entity expansion because the document defines recursive or billion-laughs entities that could exhaust memory, triggering XXE protection.
YAML — duplicate key error during parse
YAML parser throws a duplicate key error because the same key appears twice in the same mapping, which is invalid YAML and often a merge conflict artifact.
ZooKeeper — connection loss during operation
ZooKeeper client throws ConnectionLossException because the session expired or the server is unreachable, leaving ephemeral nodes in an indeterminate state.
JWT kid Not Found — Key Rotation Breaks Verification
Fix JWT verification failures during key rotation by caching the JWKS by kid, refreshing on unknown kids, and matching the alg.
NotAllowedError — Autoplay Blocked by Browser Policy
Handle NotAllowedError from play() by requiring a user gesture, muting initially, and using a fallback play control.
NotAllowedError on clipboard.writeText — Permission or Gesture
Fix clipboard write failures by calling from a user gesture, requesting the clipboard-write permission in iframes, and handling rejection.
crypto.subtle Is Undefined — Secure Context Required
Fix crypto.subtle being undefined by serving over HTTPS or localhost, since the Web Crypto API is restricted to secure contexts.
Browser ERR_BLOCKED_BY_CLIENT — Request Blocked
Diagnose ERR_BLOCKED_BY_CLIENT when ad blockers or extensions block a request, and distinguish extension blocking from CSP and CORS failures.
Browser ERR_CERT_AUTHORITY_INVALID on HTTPS
Fix Chrome ERR_CERT_AUTHORITY_INVALID for self-signed certificates and internal CAs by trusting the CA locally or using a proper development certificate.
Browser ERR_CONNECTION_REFUSED — Site Cannot Be Reached
Diagnose browser ERR_CONNECTION_REFUSED for localhost and remote hosts by checking listeners, ports, IPv6 vs IPv4 binding, and dev-server config.
Browser ERR_EMPTY_RESPONSE — Server Closed Without Data
Diagnose ERR_EMPTY_RESPONSE when the server accepts a connection then closes it without sending an HTTP response, covering crashes and proxy resets.
SecurityError — pushState Cannot Be Called on a Cross-Origin URL
Fix pushState SecurityError by keeping history URLs same-origin and passing only path, query, and hash, never a full external URL.
DOMException SecurityError — localStorage Access Denied
Fix localStorage SecurityError by wrapping access for disabled cookies or sandboxed iframes and falling back to memory storage.
Mixed Content Blocked — HTTPS Page Loading HTTP Resource
Fix mixed content blocking by serving all subresources over HTTPS, updating hardcoded http URLs, and using protocol-relative or same-origin paths.
DOMException QuotaExceededError — Storage Full
Fix QuotaExceededError from localStorage and IndexedDB by measuring usage, evicting stale entries, and requesting persistent storage.
Browser Uncaught (in promise) TypeError
Fix "Uncaught (in promise) TypeError" console errors by adding await, handling rejections, and validating response bodies before property access.
Browser Refused to Display Frame — X-Frame-Options DENY
Fix "Refused to display in a frame" by setting compatible X-Frame-Options or Content-Security-Policy frame-ancestors for the embedding origin.
C# ArgumentNullException: value cannot be null
Fix C# ArgumentNullException by tracing the null source, enabling nullable reference types, and guarding public API boundaries.
C# CS8602 — Dereference of a Possibly Null Reference
Fix CS8602 nullable warnings by adding a real null check, using the null-forgiving operator only with proof, and annotating nullability correctly.
C# FormatException: input string was not in a correct format
Fix C# FormatException from Parse and string.Format by using TryParse, culture-aware parsing, and escaping literal braces.
C# HttpClient TaskCanceledException — Timeout Not an Error
Fix HttpClient TaskCanceledException by distinguishing a request timeout from caller cancellation using CancellationToken, keeping its inner TimeoutException.
C# IndexOutOfRangeException / ArgumentOutOfRangeException
Fix index errors by checking collection bounds, using range and index operators safely, and preferring foreach or LINQ over manual indexing.
C# InvalidCastException: specified cast is not valid
Fix C# InvalidCastException when an explicit cast targets the wrong type, and use pattern matching or as-cast for safe conversion.
C# KeyNotFoundException: common causes
Fix C# KeyNotFoundException from Dictionary lookups by using TryGetValue, GetValueOrDefault, or validating the key before access.
C# ObjectDisposedException — Using a Disposed Resource
Fix ObjectDisposedException by respecting using scopes, not capturing disposed HttpClient or streams, and making ownership clear.
Docker build: failed to solve process "/bin/sh -c ..."
Diagnose Docker build "failed to solve" errors caused by a failing RUN command, missing files, or a base image that changed.
Docker daemon: TLS certificate error
Fix Docker daemon TLS errors when certificates are expired, the wrong CA is used, or the client and server names mismatch.
esbuild: Could not resolve import
Fix esbuild "Could not resolve" errors by correcting paths, adding extensions, and configuring aliases, externals, and loader settings.