name: nextjs-debugging description: Debugs Next.js App Router issues systematically. Use when hitting a build error, hydration mismatch, server action failure, or runtime crash.
Objective
Find the real root cause quickly, not just patch symptoms.
Debugging Method
Always follow this order:
- identify exact symptom
- classify where it fails
- isolate smallest failing boundary
- test assumptions against framework rules
- propose root cause
- recommend minimal fix
- mention regression checks
Classification
Place the issue into one of these buckets first:
- build-time error
- type error
- runtime server error
- runtime client error
- hydration mismatch
- data fetching or cache issue
- server action issue
- route handler issue
- auth/session issue
- environment or deployment issue
- styling or layout issue
- performance regression
Common Next.js Failure Patterns
Server / client boundary issues
Look for:
- importing server-only code into client files
- using hooks in server components
- using browser APIs on the server
- accidental
"use client"spread
Hydration issues
Look for:
- non-deterministic rendering
- date/time differences
- random values during render
- client-only logic rendered on server
- conditional markup mismatch
Server action issues
Look for:
- invalid input shape
- missing validation
- wrong redirect/revalidate usage
- swallowed errors
- action imported into the wrong layer
Data issues
Look for:
- duplicate fetches
- stale cache
- wrong revalidation assumptions
- dynamic data treated as static
- client fetching data that should be fetched server-side
Env issues
Look for:
- wrong env scope
- secret used in client code
- missing variable in deployment
- different dev vs prod assumptions
Required Output Structure
When debugging, always respond with:
Symptom
Describe the exact observed failure.
Likely Cause
State the most probable root cause, with confidence level if needed.
Why This Happens
Explain the framework or runtime rule being violated.
Fix
Give the minimal safe fix first.
Verify
List what to test after the fix.
Watch For
Mention nearby regressions or related traps.
Debugging Heuristics
- Prefer one strong root cause over many vague guesses.
- If several causes are possible, rank them.
- Separate observed facts from speculation.
- Ask what changed recently only if necessary.
- Do not recommend broad rewrites when a boundary fix is enough.
Common Checks
For stack traces
- find first app-owned frame
- identify whether it originates in route, component, action, or server util
- ignore noisy wrapper frames unless they explain context
For broken UI without crash
- inspect data shape
- inspect conditional rendering
- inspect loading/empty path
- inspect client/server split
For works in dev, fails in prod
- inspect env vars
- inspect caching
- inspect build-time assumptions
- inspect dynamic import behavior
- inspect server/client divergence
Output Style
- Be structured and calm.
- Prefer diagnosis over generic troubleshooting dumps.
- Give copy-pasteable fixes when useful.
- Keep the path from symptom to cause easy to follow.