---
name: nextjs-server-side-error-debugging
description: |-
  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.
author: Claude Code
version: 1.0.0
date: 2024-01-15
title: nextjs-server-side-error-debugging
canonical_url: https://skilld.dev/gh/blader/claudeception/nextjs-server-side-error-debugging
last_updated: 2026-10-09T02:30:27.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install blader/claudeception/nextjs-server-side-error-debugging`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/nextjs-server-side-error-debugging`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/blader/claudeception/nextjs-server-side-error-debugging) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/nextjs-server-side-error-debugging`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/nextjs-server-side-error-debugging --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/nextjs-server-side-error-debugging --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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
