nextjs-server-side-error-debugging

Next.js Server-Side Error Debugging

Problem

Server-side errors in Next.js don't appear in the browser console, making debugging frustrating when you're looking in the wrong place. The browser shows a generic error page or 500 status, but no stack trace or useful error information appears in DevTools.

Context / Trigger Conditions

This skill applies when:

• Page displays "Internal Server Error" or custom error page
• Browser console shows no errors, or only a generic fetch failure
• You're using getServerSideProps, getStaticProps, or API routes
• Error only occurs on page refresh or direct navigation (not client-side transitions)
• The error is intermittent and hard to reproduce in the browser

Common misleading symptoms:

• "Unhandled Runtime Error" modal that doesn't show the real cause
• Network tab shows 500 but response body is empty or generic
• Error disappears when you add console.log (timing issue)

Solution

Step 1: Check the Terminal

The actual error with full stack trace appears in the terminal where npm run dev or next dev is running. This is the first place to look.

# If you don't see the terminal, find the process
ps aux | grep next
# Or restart with visible output
npm run dev

Step 2: Add Explicit Error Handling

For persistent debugging, wrap server-side code with try-catch:

export async function getServerSideProps(context) {
  try {
    const data = await fetchSomething();
    return { props: { data } };
  } catch (error) {
    console.error('getServerSideProps error:', error);
    // Return error state instead of throwing
    return { props: { error: error.message } };
  }
}

Step 3: For Production Errors

Check your hosting provider's logs:

• Vercel: Dashboard → Project → Logs (Functions tab)
• AWS: CloudWatch Logs
• Netlify: Functions tab in dashboard
• Self-hosted: Check your Node.js process logs

Step 4: Common Causes

1. Environment variables: Missing in production but present locally
2. Database connections: Connection string issues, cold starts
3. Import errors: Server-only code accidentally imported on client
4. Async/await: Missing await on async operations
5. JSON serialization: Objects that can't be serialized (dates, functions)