nextjs-server-side-error-debugging_skill

Overview

This skill helps you debug server-side errors in Next.js pages and API routes when the browser shows a generic error but devtools are empty. It focuses on inspecting the server/terminal logs, adding targeted server-side error handling, and checking common causes like environment variables and imports. Use it to quickly find the real stack trace and root cause for getServerSideProps, getStaticProps, and API route failures.

How this skill works

The skill directs you to check the terminal where next dev or your production Node process runs, because Next.js prints full stack traces there. It also walks through adding try/catch around server-side functions, returning safe error props, and locating host-specific logs (Vercel, AWS, Netlify, self-hosted). Finally, it lists common failure modes and verification steps so you can confirm the issue is resolved.

When to use it

• Page shows "Internal Server Error" but browser console has no useful stack trace
• API route returns 500 with an empty or generic response body
• Error occurs only on full page refresh or direct navigation, not client-side routing
• Server-side code appears to fail silently or intermittently
• You want the authoritative source of runtime errors (terminal/host logs) instead of DevTools

Best practices

• Always check the terminal running npm run dev or next dev first for the full stack trace
• Wrap getServerSideProps/getStaticProps and API handlers in try/catch and log errors to console
• Return a safe error state from server functions instead of throwing in production
• Verify environment variables and database connections in the environment where the error occurs
• Avoid importing server-only modules into client bundles and watch for serialization issues (dates, functions)

Example use cases

• A dashboard route returns 500 on refresh; terminal shows undefined property access in getServerSideProps
• An API route works in client navigation but fails with 500 on direct fetch; host logs reveal missing env var
• Intermittent production failures traced to cold DB connections visible in CloudWatch or Vercel function logs
• Development overlay shows generic error but terminal reveals import error from a server-only package