blader/claudeception/nextjs-server-side-error-debugging

Claude Code and agent skill by blader/claudeception

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Debug getServerSideProps and getStaticProps errors in Next.js. Use when: (1) Page shows generic error but browser console is empty, (2) API routes return 500 with no details, (3) Server-side code fails silently, (4) Error only occurs on refresh not client navigation. Check terminal/server logs instead of browser for actual error messages.

Install

npx vskill@latest install blader/claudeception/nextjs-server-side-error-debugging

SKILL.md

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.

bash
# 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:

typescript
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)

Verification

After checking the terminal, you should see:

  • Full stack trace with file name and line number
  • The actual error message (not generic 500)
  • Variable values if you added console.log statements

Example

Symptom: User reports page shows "Internal Server Error" after clicking a link.

Investigation:

  1. Open browser DevTools → Console: Empty
  2. Network tab shows: GET /dashboard → 500
  3. Check terminal running npm run dev:
Error: Cannot read property 'id' of undefined
at getServerSideProps (/app/pages/dashboard.tsx:15:25)
at renderToHTML (/app/node_modules/next/dist/server/render.js:428:22)

Cause found: Database query returned null instead of user object.

Notes

  • In development, Next.js sometimes shows an error overlay, but it often has less

detail than the terminal output

  • reactStrictMode: true in next.config.js causes double-execution of server

functions in development, which can make debugging confusing

  • For API routes, the error appears in the same terminal as page errors
  • Client-side errors (in useEffect, event handlers) DO appear in browser console—

this skill only applies to server-side code

  • If using next start (production mode locally), errors may be less verbose;

check NODE_ENV and consider adding custom error logging

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

7-day trend score
0

Refreshed 19 Mar 2026, 8 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/blader/claudeception/nextjs-server-side-error-debugging/badge)](https://verified-skill.com/skills/blader/claudeception/nextjs-server-side-error-debugging)

Something wrong with this skill or its page? Tell us.