HTTP 500 Internal Server Error — What It Means and How to Fix It

What causes this error

HTTP 500 is a catch-all for any unhandled exception on the server. Common causes: unhandled promise rejection in Node.js, null pointer dereference, database query failure (connection lost, query timeout, constraint violation), missing environment variable, incorrect import path in production build, out-of-memory crash, or a syntax error introduced in a recent deployment.

How to fix it

1. 01

   step 1

   Check the server logs immediately

   500s are logged server-side with full stack traces. The response body is usually generic ('Internal Server Error') to avoid leaking implementation details. The stack trace in your log is the only path to the root cause.

   # Kubernetes pod logs
   kubectl logs -f deployment/my-api --tail=100
   
   # Systemd service
   journalctl -u my-service -f -n 100
   
   # AWS CloudWatch
   aws logs tail /aws/lambda/my-function --follow

   Copy
2. 02

   step 2

   Correlate the 500 with a deployment

   Most 500s start after a deployment. Check your deployment history: what changed in the last release? Pay special attention to dependency version bumps, environment variable changes, and database migrations.

   # Recent git changes
   git log --oneline -10
   git diff HEAD~1 HEAD -- package.json
   
   # Environment variables diff — compare against working version
   # Never commit .env but do document changes in your deployment notes

   Copy
3. 03

   step 3

   Reproduce locally with production-equivalent settings

   Set `NODE_ENV=production` locally and run the exact build artifact. Many bugs only appear in production because dev mode has additional error handling, different module resolution, or disabled optimizations.

   # Reproduce production build locally
   NODE_ENV=production npm run build
   NODE_ENV=production npm start
   
   # Test the exact failing request
   curl -X POST http://localhost:3000/api/failing-endpoint \
     -H 'Content-Type: application/json' \
     -d '{"same": "payload as production"}'

   Copy
4. 04

   step 4

   Add global unhandled exception and rejection handlers

   In Node.js, unhandled promise rejections cause 500s without appearing in request logs. Add global handlers to catch and log them with full context.

   process.on('unhandledRejection', (reason, promise) => {
     console.error('Unhandled Rejection at:', promise, 'reason:', reason)
     // In production: send to error tracker (Sentry, Datadog)
   })
   
   process.on('uncaughtException', (err) => {
     console.error('Uncaught Exception:', err)
     process.exit(1)  // Let the process manager restart the process
   })

   Copy
5. 05

   step 5

   Check for database connection failures

   A lost database connection causes every subsequent query to throw, resulting in 500s on every request. Check connection pool health, `max_connections` limits, and whether your DB host is reachable.

   # PostgreSQL — check active connections
   psql -U postgres -c "SELECT count(*) FROM pg_stat_activity;"
   
   # Check max connections
   psql -U postgres -c "SHOW max_connections;"
   
   # Node.js — log pool state
   pool.on('error', (err) => console.error('Pool error:', err))

   Copy

How to verify the fix

• Curl the failing endpoint — it now returns a 2xx response.
• Server logs show no new error entries during a test request.
• Error monitoring (Sentry, Datadog) shows 500 rate returning to baseline.