How to Fix
Next.js 500 Errors

What Is a 500 Error in Next.js?

Unlike specific error codes (404, 401, 403), a 500 error means the server encountered an unexpected condition. In Next.js, this usually means an unhandled exception in a Server Component, API route, or middleware.

The error page shows "500" because Next.js caught the error but could not recover from it. The actual error is in your server logs.

Step 1: Check Server Logs

Before doing anything else, check your server logs. In development, this is the terminal where you ran npm run dev. In production on Vercel, check the function logs in the Vercel dashboard.

Look for the error message — it will tell you exactly what went wrong and where. Common patterns: "Cannot find module", "TypeError: undefined is not a function", "Promise rejected".

Common Cause: Unhandled Promise Rejection

Async code that throws without being caught causes a 500 error.

Fix: Wrap async code in try-catch. Always handle promise rejections in API routes and Server Components.

Common Cause: Missing Environment Variable

Code tries to access process.env.VARIABLE_NAME but the variable is not set in production.

Fix: Add the missing environment variable to your hosting platform dashboard. Make sure it matches the exact name used in your code.

Common Cause: TypeScript Errors in Production

TypeScript errors that are ignored in development cause runtime errors in production.

Fix: Run tsc --noEmit locally and fix all errors. Do not ignore TypeScript errors — they indicate real problems.

Common Cause: Database Connection Failure

The database is unreachable or the connection string is wrong in production.

Fix: Verify the database URL is correct. Check that the database server is running. Verify SSL settings match what your database provider requires.

Getting Help

If you cannot find the cause from logs, get expert help. 500 errors can have hidden causes that are hard to diagnose.