How to Debug a Next.js Application in VS Code (App Router Guide)

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    }
  ]
}

Start debugging with F5. Set breakpoints in any Server Component, layout.jsx, or route.ts file. When a page request hits, the debugger pauses —
you can inspect server-side variables, auth state, and database query results directly.

▎ Note: In Next.js 14+ App Router, breakpoints work in both Server Components (server-side, in the terminal debugger) and Route Handlers. Client
▎ Components need the browser DevTools debugger, not the VS Code debugger.

Debugging Client-Side Errors (Client Components)

Client Components render in the browser. Their errors show in DevTools (F12 → Console).

The React Error Overlay

In dev mode, unhandled Client Component errors show a red overlay with the component stack:

TypeError: Cannot read properties of null (reading 'user')

The above error occurred in the <ProfileCard> component:
    at ProfileCard (src/components/ProfileCard.jsx:12)
    at div
    at UserDashboard (src/app/dashboard/page.jsx:18)

Read the component stack bottom-up to find which component caused the error and which parent rendered it.

Use Chrome DevTools Sources Panel

For complex client-side bugs:

1. Open DevTools → Sources tab
2. Press Ctrl+P → type the component filename
3. Click a line number to set a breakpoint
4. Trigger the action that causes the error
5. Execution pauses — inspect variable state in the right panel

▎ Tip: Next.js dev mode generates source maps automatically. You can debug your original .jsx/.tsx files in DevTools — not the compiled output.
▎ Source maps make line numbers and variable names match your actual code.

Common Client-Side Errors

Error: Hydration failed because the server rendered HTML didn't match the client

Cause: Component renders differently on server vs client — usually new Date(), Math.random(), or window access during render. Fix: move to
useEffect. Full guide: How to Fix the Next.js Hydration Error (/blog/fix-nextjs-hydration-error).

Error: useState can only be used in a Client Component.
Add the "use client" directive at the top of the file.

▎ Fix: Add 'use client' as the very first line of the component file — above all imports.

Debugging API Routes

API routes (app/api/*/route.ts) run server-side. Errors print to terminal.

// app/api/users/route.ts
export async function POST(request: Request) {
    const body = await request.json()
    // Set breakpoint here to inspect body
    const user = await createUser(body)
    return Response.json(user)
}

Test API routes with curl or the REST Client VS Code extension:

curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

▎ Tip: Install the "REST Client" VS Code extension. Create a .http file in your project to save test requests alongside your code. Faster than
▎ Postman for rapid iteration.

Debugging Build Errors

next build errors stop deployment. Three main categories:

TypeScript Errors

Type error: Type 'string | null' is not assignable to type 'string'.

Run npx tsc --noEmit locally before pushing. Catches all TypeScript errors without doing a full build. Faster feedback loop.

Missing Environment Variables

Next.js fails the build if a NEXT_PUBLIC_* variable referenced in code isn't set:

▎ Error: ReferenceError: NEXT_PUBLIC_API_URL is not defined

▎ Fix: Add the variable to your deployment environment (Vercel dashboard → Settings → Environment Variables) AND to your local .env.local. Never
▎ hardcode URLs.

Static Generation Failures

Server Components that fail during next build (when Next.js tries to statically generate pages) cause build errors with a long trace:

Error occurred prerendering page "/blog/[slug]"
...
Error: fetch failed

This means your page called a fetch that failed at build time. Use next: { revalidate: 3600 } instead of cache: 'no-store' so Next.js generates
the page once and caches it, rather than fetching at every build.

The Debugging Workflow in Order

When a Next.js error occurs, check these in order:

1. Terminal — server error? Full stack trace here.
2. Browser console — client error? Component stack here.
3. / route vs specific route — does the homepage work? If yes, the bug is route-specific.
4. Network tab — API route returning wrong status? Check request/response here.
5. next build locally — build error before deploying? Run the build and read the output.

▎ Note: Don't deploy to test a bug. Reproduce it in next dev first. Build errors that only appear on Vercel are almost always environment variable
▎  mismatches — your local .env.local has values your deployment doesn't.

Cross-File Errors in App Router

App Router introduces complex dependency chains: layout → page → server component → service → database. An error deep in a database query can
surface with a misleading stack trace pointing to the layout.

For these errors, DebugAI reads your full component tree — the page, its layout, the server actions it calls, the service functions those actions
use — and identifies the root cause without you having to follow the chain manually.

▎ Tip: The most time-consuming Next.js bugs are auth errors that appear as 404s or blank pages (middleware redirecting silently) and data-fetching
▎  bugs where null propagates from a database query through 3 layers before causing an error. Both are fast to solve with codebase-aware analysis.

Quick Reference

┌────────────────────────────────┬────────────────────────┬────────────────────────────────────┐
│           Error type           │    Where it appears    │            Tool to use             │
├────────────────────────────────┼────────────────────────┼────────────────────────────────────┤
│ Server Component runtime error │ Terminal               │ VS Code debugger + terminal trace  │
├────────────────────────────────┼────────────────────────┼────────────────────────────────────┤
│ Client Component runtime error │ Browser console        │ Chrome DevTools + error overlay    │
├────────────────────────────────┼────────────────────────┼────────────────────────────────────┤
│ Hydration mismatch             │ Browser console        │ Check server vs client render diff │
├────────────────────────────────┼────────────────────────┼────────────────────────────────────┤
│ API route error                │ Terminal + network tab │ curl test + terminal trace         │
├────────────────────────────────┼────────────────────────┼────────────────────────────────────┤
│ Build error                    │ next build output      │ Fix TypeScript/env first           │
├────────────────────────────────┼────────────────────────┼────────────────────────────────────┤
│ Auth/middleware redirect bug   │ No error, blank page   │ Check middleware.ts conditions     │
└────────────────────────────────┴────────────────────────┴────────────────────────────────────┘

Debug faster starting today.

Free VS Code extension. 10 sessions/day. No credit card.