version: "1.0.0" name: nextjs-debug description: Framework diagnostics for Next.js applications. Troubleshoots API route 404/405 errors, middleware redirect loops, SSR/hydration issues, and server/client component problems. Use when facing Next.js-specific issues. Triggers on "nextjs debug", "404 error", "405 error", "middleware issue", "hydration error", "server component", "client component", "API route not working". context: fork model: haiku allowed-tools: Read, Glob, Grep, Bash(npm ), Bash(npx next )

Next.js Debug Skill - Framework Diagnostics

Purpose

Quickly diagnose and resolve common Next.js issues by running targeted diagnostic checks and providing specific solutions.

Issue Categories

1. API Route Issues (404/405)

Symptoms:

• POST request returns 404
• API route returns 405 Method Not Allowed
• API works in development but not production

Diagnostic Steps:

# 1. Verify route file exists
ls -la app/api/[endpoint]/route.ts
 
# 2. Check exported HTTP methods
grep -E "export (async )?function (GET|POST|PUT|DELETE|PATCH)" app/api/*/route.ts
 
# 3. Check middleware configuration
grep -A 10 "matcher" middleware.ts
 
# 4. Look for API exclusion in middleware
grep "api" middleware.ts

Common Fixes:

Middleware Fix Template:

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)']
};

2. Middleware Redirect Loops

Symptoms:

• Browser shows "too many redirects"
• Page never loads
• Request keeps bouncing between paths

Diagnostic Steps:

# 1. Check middleware redirect conditions
grep -A 20 "redirect\|NextResponse.redirect" middleware.ts
 
# 2. Check authentication logic
grep -B 5 -A 10 "if.*authenticated\|if.*session\|if.*cookie" middleware.ts
 
# 3. Check matcher scope
grep "matcher" middleware.ts

Common Fixes:

3. Hydration Mismatches

Symptoms:

• Console warning: "Hydration failed because the initial UI does not match"
• Content flickers on page load
• Interactive elements don't work initially

Diagnostic Steps:

# 1. Find browser-only APIs
grep -rn "window\.\|document\.\|localStorage\|sessionStorage" src/ --include="*.tsx"
 
# 2. Find date/time rendering
grep -rn "new Date\|toLocaleString\|Date\.now" src/ --include="*.tsx"
 
# 3. Find random values
grep -rn "Math\.random\|uuid\|nanoid" src/ --include="*.tsx"
 
# 4. Find conditional rendering that could differ
grep -rn "typeof window\|process\.browser" src/ --include="*.tsx"

Common Fixes:

Pattern:

// BAD - runs on server with different value
const time = new Date().toLocaleString();
// GOOD - only runs on client
const [time, setTime] = useState<string>();
useEffect(() => {
  setTime(new Date().toLocaleString());
}, []);

4. Server/Client Component Issues

Symptoms:

• Error: "useState is not a function"
• Error: "Hooks can only be called inside a function component"
• Error: "You're importing a component that needs X"

Diagnostic Steps:

# 1. Find files using React hooks
grep -rn "useState\|useEffect\|useRef\|useContext\|useCallback\|useMemo" src/ --include="*.tsx" -l
 
# 2. Check which have 'use client'
for f in $(grep -rn "useState\|useEffect" src/ --include="*.tsx" -l); do
  if ! grep -q "use client" "$f"; then
    echo "Missing 'use client': $f"
  fi
done
 
# 3. Find event handlers (need client component)
grep -rn "onClick\|onChange\|onSubmit" src/ --include="*.tsx" -l

Common Fixes:

5. Build/Bundle Issues

Symptoms:

• Build fails with module errors
• Unexpected bundle size
• "Module not found" errors

Diagnostic Steps:

# 1. Check for circular dependencies
npx madge --circular src/
 
# 2. Analyze bundle size
npm run build
npx @next/bundle-analyzer
 
# 3. Check for server-only imports in client
grep -rn "from 'fs'\|from 'path'\|from 'crypto'" src/ --include="*.tsx"

Quick Diagnostic Command

Run this for a quick health check:

echo "=== Next.js Diagnostic ===" && \
echo "Middleware:" && ls -la middleware.ts 2>/dev/null || echo "No middleware" && \
echo "API Routes:" && find app/api -name "route.ts" 2>/dev/null | head -10 && \
echo "Client Components:" && grep -rl "use client" src/ 2>/dev/null | wc -l && \
echo "Server Hooks Usage:" && grep -rn "useState\|useEffect" src/ --include="*.tsx" 2>/dev/null | grep -v "use client" | head -5

Debugging Workflow

1. Identify the error type (404, hydration, hooks, etc.)
2. Run targeted diagnostics for that category
3. Check the common fixes table
4. Apply the fix
5. Verify with build: npm run build

Integration

This skill works with:

• framework-specialist-agent for complex issues
• /validate-build for verification after fixes
• nextjs-app-router-patterns.md rule for prevention

Quick Reference

File Checklist for API Routes

• [ ] File is at app/api/[endpoint]/route.ts
• [ ] HTTP method function is exported
• [ ] Method name is uppercase (GET, POST, etc.)
• [ ] Middleware excludes /api/*
• [ ] No page.tsx in same folder

File Checklist for Client Components

• [ ] 'use client' at very top of file
• [ ] No server-only imports
• [ ] All hooks are inside component body
• [ ] Event handlers are in client components