Production-only 500 error checklist for API routes that pass local tests

A production-only 500 error should be checked against config, data shape, permissions, and runtime differences before rewriting the route.

Local tests prove one environment, not every environment. A route can pass locally and still fail in production because the database has different rows, the process uses different permissions, a required secret is missing, a dependency version differs, or the runtime blocks a filesystem or network call. The first step is to identify what production has that local does not.

Start with the exact request. Capture method, path, status, request ID, user role, and safe input fields. Then find the first server log for that request ID. Do not start with the last error in the chain if earlier validation, auth, or configuration errors are visible. A good log line should show the failing boundary without exposing secrets.

Next, compare data. Production may contain nulls, longer strings, older records, deleted relations, or feature flags that local seed data never covered. If the route assumes a relation always exists, production will find the exception first. Add a targeted query or safe diagnostic count to confirm the shape before patching.

Finally, compare runtime. Serverless timeouts, read-only filesystems, region latency, missing native libraries, and stricter CORS or cookie settings can all create production-only failures. The checklist keeps the fix narrow: prove the failing boundary, then change the smallest code or config path that explains it.

Production-only 500 error checklist for API routes that pass local tests

// COMMENTS

ON THIS PAGE