Debugging 500 Internal Server Error

Step 1 — Find the Real Error

The browser shows "500 Internal Server Error" but that tells you nothing. The actual error is in your server logs.

# Tail logs in real time while reproducing the error
tail -f /var/log/nginx/error.log
# or
docker logs -f my-app

Step 2 — Common Causes

Unhandled exception / missing try-catch

The most common cause. An exception is thrown and nothing catches it.

// ❌ No error handling
app.get('/api/data', async (req, res) => {
  const data = await db.query('SELECT * FROM users') // throws if DB is down
  res.json(data)
})

// ✅ Catch and handle
app.get('/api/data', async (req, res) => {
  try {
    const data = await db.query('SELECT * FROM users')
    res.json(data)
  } catch (err) {
    console.error('DB query failed:', err)
    res.status(500).json({ error: 'Internal server error' })
  }
})

Database connection failure

Look for errors like ECONNREFUSED or Too many connections. Check that the database is running and the connection string is correct in environment variables.

Missing environment variable

A missing env var causes undefined errors at runtime. Validate all required env vars at startup.

# Check what env vars are set
printenv | grep DATABASE
# or in Node.js
console.log(process.env.DATABASE_URL)

Syntax error in recently deployed code

A syntax error in a module causes the entire server to fail on startup or on first import.

# Node.js — check for syntax errors
node --check src/app.js

# Python
python -m py_compile app.py

Out of memory / resource exhaustion

Look for JavaScript heap out of memory or similar. Increase memory limits or find the memory leak.

File not found / wrong path

Paths that work locally may differ in production (especially in Docker). Use path.join(__dirname, 'config.json') instead of relative paths.

Step 3 — Add Proper Error Handling

Express.js — global error handler

// Must be defined AFTER all routes
app.use((err, req, res, next) => {
  console.error({
    message: err.message,
    stack: err.stack,
    path: req.path,
    method: req.method
  })

  const status = err.status ?? 500
  res.status(status).json({
    error: status < 500 ? err.message : 'Internal server error'
  })
})

// Use express-async-errors to catch async throws automatically
require('express-async-errors')

Next.js App Router

// app/api/data/route.ts
export async function GET() {
  try {
    const data = await fetchData()
    return Response.json(data)
  } catch (err) {
    console.error('GET /api/data:', err)
    return Response.json({ error: 'Internal server error' }, { status: 500 })
  }
}

Django

# settings.py — production settings
DEBUG = False
LOGGING = {
    'version': 1,
    'handlers': {
        'file': {
            'class': 'logging.FileHandler',
            'filename': '/var/log/django/error.log',
        },
    },
    'root': {
        'handlers': ['file'],
        'level': 'ERROR',
    },
}

Step 4 — Prevention Checklist

• All async operations wrapped in try/catch
• Global error handler catches unhandled exceptions
• Environment variables validated at startup (fail fast)
• Database connection errors handled gracefully
• Stack traces never sent to clients in production
• Health check endpoint (/health) to verify DB/service connectivity
• Structured logging with request context (path, method, user ID)
• Alerts configured for 5xx error rate spikes