Debugging guides for real production failures.

Environment variable undefined in production: how to debug it

Your app reads `process.env.DATABASE_URL` and gets `undefined` in production — but it works locally. Track down the injection gap.

Works locally but fails in production: how to debug it

Your code runs fine on your machine but breaks the moment it hits staging or production. Here is a structured approach to find the gap.

File upload works locally but fails in production: how to debug it

Your upload endpoint works with local files but returns errors in production. The filesystem, permissions, size limits, or storage backend is different.

API returns 500 only in production: how to debug it

Your API endpoint returns 200 locally but 500 in production. Some code path that never triggers in dev fires in the real environment.

Production-only bug: a systematic debugging checklist

A bug only appears in production. You cannot reproduce it locally. Here is a systematic checklist to find environment-specific failures.

( 02 )CI/CD debugging

Node version mismatch in CI: how to debug it

Your code uses a feature from Node 20 but CI runs Node 18. Build fails with a syntax error or missing API. The fix is one line in the CI config.

npm install works locally but fails in CI: how to debug it

npm install completes on your machine but CI throws errors. The issue is usually a clean environment gap: missing native build tools, lockfile drift, or platform-specific binaries.

GitHub Actions missing secret: how to debug CI secret issues

Your GitHub Actions workflow references a secret that does not exist in the repository settings. The workflow fails with an empty value or an error.

Tests pass locally but fail in CI: how to debug it

Green locally, red in CI. The diff is usually environment, ordering, or a clean-install gap. Here is how to narrow it down fast.

Frontend build works locally but fails on Vercel or Render: how to debug it

Your build command succeeds locally but fails when Vercel or Render runs it. The platform has a different Node version, memory limit, or build settings.

Flaky tests in CI: how to debug and fix intermittent test failures

A test passes nine times out of ten but randomly fails in CI with no code changes. Flaky tests destroy trust in the test suite — here is how to find and fix them.

( 03 )API/backend debugging

API returns 404 after deploy: how to debug it

Your API endpoint works locally but returns 404 after deployment. The route is in your code — the server just cannot find it.

Slow API response: how to debug latency issues

An API endpoint that used to return in 50ms now takes 3 seconds. Find the bottleneck before your users notice.

N+1 query slowing down your API: how to find and fix it

Your API makes one query to get a list, then one more query for every item in the list. That is the N+1 pattern — it turns 1 query into 101 and kills performance.

API timeout: how to debug request timeout issues

Your API endpoint returns a timeout error. The request takes longer than the configured timeout, but the operation might have succeeded silently on the server.

( 04 )Environment/config debugging

CORS error after deployment: how to debug it

API works fine in dev but browsers block requests after deploy with a CORS error. Find the origin mismatch and fix it.

Redirect URL wrong in production: how to debug redirect bugs

Your app redirects users to `http://localhost:3000/dashboard` in production. The redirect URL is hardcoded, or the origin detection is picking up the wrong value.

Deployment config mismatch: how to debug environment-specific config bugs

Your staging environment works. Production does not. The code is the same but the config is different — a missing setting, a wrong endpoint, or a different feature flag value.

Feature flag bug: how to debug unexpected feature flag behaviour

A feature flag is supposed to be off for some users but is on for everyone, or vice versa. The flag value, targeting rules, or flag evaluation is wrong.

( 05 )Docker/deployment debugging

Docker container cannot connect to localhost: how to debug it

Your app inside Docker tries to reach a service on localhost and gets connection refused. The fix is understanding Docker networking.

Case-sensitive import fails on Linux: how to debug it

Your import works on macOS and Windows but fails on Linux with 'module not found'. The fix is a single character.

Cron job not running in production: how to debug scheduled tasks

Your cron job runs fine when triggered manually but never fires on its schedule in production. The scheduler, timezone, or environment is wrong.

SSL certificate error after deployment: how to debug TLS issues

Your site was working with HTTPS. After a deployment, browsers show SSL errors. The certificate expired, was not renewed, or the domain changed.

Kubernetes pod CrashLoopBackOff: how to debug crashing pods

Your pod starts, crashes, restarts, crashes again. The CrashLoopBackOff status means Kubernetes is giving up. The pod logs hold the answer.

( 06 )Database/debugging

Pagination off by one bug: how to debug pagination errors

Your paginated list skips the first item, shows the last item twice, or has an empty last page. The offset, limit, or page calculation is off by one.

Database transaction rollback not working: how to debug it

Your code calls rollback but the data stays committed. The transaction was never really open, or it auto-committed before the failure.

Stale cache key bug: how to debug cache key collisions

Your cache returns data belonging to a different user, tenant, or request. The cache key is not unique enough — it is missing a dimension.

Database migration works locally but fails in production: how to debug it

Your migration runs perfectly on your local database but errors out in production. Different database version, different data, or different permissions.

Tenant cache leak: how to debug cross-tenant data exposure through caching

A user from Tenant A sees data from Tenant B because the cache key does not include the tenant identifier. The cache is leaking data across tenants.

( 07 )Cache/queue/distributed bugs

Intermediate

Redis cache serving stale data: how to debug it

Your Redis cache returns old data after the source of truth updates. The cache key, TTL, or invalidation is wrong.

Retry logic creating duplicate requests: how to debug it

Your retry logic fires a second request before the first one finishes. The server processes both. Now you have two charges, two emails, or two orders.

Webhook fires twice: how to debug duplicate webhook deliveries

Your webhook endpoint receives the same event twice. The provider retried because your endpoint did not acknowledge fast enough, or your handler is not idempotent.

Queue consumer not processing messages: how to debug it

Messages pile up in the queue but your consumer does nothing. The consumer might be crashed, stuck, or silently discarding messages.

Distributed lock not releasing: how to debug stuck locks

Your distributed lock is acquired but never released. The lock holder crashed, the TTL expired but the key lingers, or the unlock logic has a bug.

( 08 )JavaScript/Node runtime debugging

Request body undefined in Express: how to debug missing request bodies

Your Express route handler receives `req.body` as `undefined` or an empty object. The body parser is missing, misconfigured, or not matching the content type.

Timezone off by one day in JavaScript: how to debug it

Your date shows the wrong day because of a timezone offset. The date string, parser, or display format is silently shifting it.

ESM CommonJS import error: how to debug module system conflicts

Your import breaks with 'require is not defined' or 'Cannot use import outside a module'. The file is being treated as the wrong module system.

Hidden state bug in React form: how to debug stale closures and state issues

Your React form submits old values, or a callback sees stale state. A closure captured a variable from a previous render and never updated.

Worker process memory leak: how to find and fix memory leaks in background jobs

Your background worker's memory usage grows steadily until it crashes. The leak is accumulating across jobs — each job leaves something behind.

Stale lock bug: how locks that are never refreshed cause outages

A lock is acquired, the operation succeeds, but the lock is never released or refreshed. Other processes wait until the lock TTL expires, causing delays or outages.

( 09 )Auth/session/payment bugs

Intermediate

JWT token invalid after deployment: how to debug it

JWTs work locally and in staging, but after a production deploy every token is rejected. The secret, algorithm, or clock changed.

Session cookie not working after deployment: how to debug it

Users were logged in. You deploy. Everyone is logged out. The session cookie is not being sent, not being recognised, or being set with wrong attributes after the new deployment.

OAuth callback URL mismatch: how to debug OAuth redirect errors

OAuth login fails with 'redirect_uri_mismatch' after deployment. The callback URL in the request does not exactly match what is registered with the OAuth provider.

Idempotency key not preventing duplicate payment: how to debug it

Your payment API accepts an idempotency key but still processes the same charge twice. The key is not being checked, stored, or matched correctly.

Race condition in payment flow: how to debug concurrent payment issues

Two requests hit the payment endpoint at the same time. Both check the balance, both see enough funds, and both deduct. The user is charged twice.