---
name: nextjs-api-route-debugger
description: "Gets a failing Next.js API route working again: ranks the likely causes behind the error message, tells you exactly what to log where, and hands you a fix you can paste in. Use when a Next.js API route throws or returns the wrong thing and the error message needs tracing to a cause and a fix. Do not use for writing a new route from a spec or tuning a working route for performance. Related topics: coding, next.js."
---

# Next.js API Route Debugger

Gets a failing Next.js API route working again: ranks the likely causes behind the error message, tells you exactly what to log where, and hands you a fix you can paste in.

## When to use

Use this skill when a Next.js API route throws or returns the wrong thing and the error message needs tracing to a cause and a fix. Do not use it for writing a new route from a spec or tuning a working route for performance.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Parse the error name, the thing it names, and the top stack frame to locate the failing layer before proposing anything.
3. Rank candidate causes by fit with the message, method, body sample, and environment, most likely first.
4. Give each cause one confirming log line or curl command and where to place it.
5. Write the corrected handler or exact line changes plus a guard against the same class of bug.
6. Deliver the document with Problem Summary, Common Causes, Step-by-step Debugging Steps, Sample Fix Code, and Checklist in that order.

## Inputs

- **Route path** (free text, e.g. "/api/example")
- **HTTP method** (choose one: GET, POST, PUT, DELETE, PATCH)
- **Error message** (longer free text)
- **Route source (optional)** (longer free text)
- **Request body sample** (longer free text)
- **Expected response** (longer free text)
- **Environment** (choose one: Development, Production)

## Output

A markdown document with sections in this exact order: Problem Summary, Common Causes (ranked list), Step-by-step Debugging Steps, Sample Fix Code (fenced), Checklist.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Next.js API Route Debugger

Help me debug this Next.js API route.

- Route path: {{Route path}}
- HTTP method: {{HTTP method}}
- Error message: {{Error message}}
- Route source (optional): {{Route source (optional)}}
- Request body sample: {{Request body sample}}
- Expected response: {{Expected response}}
- Environment: {{Environment}}

Read the error message literally before theorizing: the thrown name, the property or module it names, and the top stack frame point at the layer that failed (parsing, auth, handler, data access, response). Rank the causes by how well they fit the message, the method, and the body sample; the usual suspects are an unparsed body (missing content type or bodyParser disabled), a method mismatch, an environment variable present locally and absent in production, an async call without await, a response sent twice, and a module that only works server side being imported into a client bundle. For each cause give the one log line or curl command that confirms or rules it out, placed before the failing line. Treat production differently: no stack traces in responses, check the deployment logs and the function timeout, and confirm the environment variables actually exist there. Write the fix as the corrected handler or the specific lines to change, and add the guard that stops the same class of bug next time. Return a markdown document with these sections in this order: Problem Summary, Common Causes (ranked), Step-by-step Debugging Steps, Sample Fix Code, Checklist.

## Pitfalls

- Guessing a cause that contradicts the stack trace because it is the most common bug in general.
- Suggesting console.log of the whole request object, which prints secrets into production logs.
- Fixing the symptom with a null check and leaving the missing await that caused it.
