| 1 | # Debug Tricks |
| 2 | |
| 3 | Tricks to speed up debugging Next.js applications. |
| 4 | |
| 5 | ## MCP Endpoint (Dev Server) |
| 6 | |
| 7 | Next.js exposes a `/_next/mcp` endpoint in development for AI-assisted debugging via MCP (Model Context Protocol). |
| 8 | |
| 9 | - **Next.js 16+**: Enabled by default, use `next-devtools-mcp` |
| 10 | - **Next.js < 16**: Requires `experimental.mcpServer: true` in next.config.js |
| 11 | |
| 12 | Reference: https://nextjs.org/docs/app/guides/mcp |
| 13 | |
| 14 | **Important**: Find the actual port of the running Next.js dev server (check terminal output or `package.json` scripts). Don't assume port 3000. |
| 15 | |
| 16 | ### Request Format |
| 17 | |
| 18 | The endpoint uses JSON-RPC 2.0 over HTTP POST: |
| 19 | |
| 20 | ```bash |
| 21 | curl -X POST http://localhost:<port>/_next/mcp \ |
| 22 | -H "Content-Type: application/json" \ |
| 23 | -H "Accept: application/json, text/event-stream" \ |
| 24 | -d '{ |
| 25 | "jsonrpc": "2.0", |
| 26 | "id": "1", |
| 27 | "method": "tools/call", |
| 28 | "params": { |
| 29 | "name": "<tool-name>", |
| 30 | "arguments": {} |
| 31 | } |
| 32 | }' |
| 33 | ``` |
| 34 | |
| 35 | ### Available Tools |
| 36 | |
| 37 | #### `get_errors` |
| 38 | |
| 39 | Get current errors from dev server (build errors, runtime errors with source-mapped stacks): |
| 40 | |
| 41 | ```json |
| 42 | { "name": "get_errors", "arguments": {} } |
| 43 | ``` |
| 44 | |
| 45 | #### `get_routes` |
| 46 | |
| 47 | Discover all routes by scanning filesystem: |
| 48 | |
| 49 | ```json |
| 50 | { "name": "get_routes", "arguments": {} } |
| 51 | // Optional: { "name": "get_routes", "arguments": { "routerType": "app" } } |
| 52 | ``` |
| 53 | |
| 54 | Returns: `{ "appRouter": ["/", "/api/users/[id]", ...], "pagesRouter": [...] }` |
| 55 | |
| 56 | #### `get_project_metadata` |
| 57 | |
| 58 | Get project path and dev server URL: |
| 59 | |
| 60 | ```json |
| 61 | { "name": "get_project_metadata", "arguments": {} } |
| 62 | ``` |
| 63 | |
| 64 | Returns: `{ "projectPath": "/path/to/project", "devServerUrl": "http://localhost:3000" }` |
| 65 | |
| 66 | #### `get_page_metadata` |
| 67 | |
| 68 | Get runtime metadata about current page render (requires active browser session): |
| 69 | |
| 70 | ```json |
| 71 | { "name": "get_page_metadata", "arguments": {} } |
| 72 | ``` |
| 73 | |
| 74 | Returns segment trie data showing layouts, boundaries, and page components. |
| 75 | |
| 76 | #### `get_logs` |
| 77 | |
| 78 | Get path to Next.js development log file: |
| 79 | |
| 80 | ```json |
| 81 | { "name": "get_logs", "arguments": {} } |
| 82 | ``` |
| 83 | |
| 84 | Returns path to `<distDir>/logs/next-development.log` |
| 85 | |
| 86 | #### `get_server_action_by_id` |
| 87 | |
| 88 | Locate a Server Action by ID: |
| 89 | |
| 90 | ```json |
| 91 | { "name": "get_server_action_by_id", "arguments": { "actionId": "<action-id>" } } |
| 92 | ``` |
| 93 | |
| 94 | ### Example: Get Errors |
| 95 | |
| 96 | ```bash |
| 97 | curl -X POST http://localhost:<port>/_next/mcp \ |
| 98 | -H "Content-Type: application/json" \ |
| 99 | -H "Accept: application/json, text/event-stream" \ |
| 100 | -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"get_errors","arguments":{}}}' |
| 101 | ``` |
| 102 | |
| 103 | ## Rebuild Specific Routes (Next.js 16+) |
| 104 | |
| 105 | Use `--debug-build-paths` to rebuild only specific routes instead of the entire app: |
| 106 | |
| 107 | ```bash |
| 108 | # Rebuild a specific route |
| 109 | next build --debug-build-paths "/dashboard" |
| 110 | |
| 111 | # Rebuild routes matching a glob |
| 112 | next build --debug-build-paths "/api/*" |
| 113 | |
| 114 | # Dynamic routes |
| 115 | next build --debug-build-paths "/blog/[slug]" |
| 116 | ``` |
| 117 | |
| 118 | Use this to: |
| 119 | |
| 120 | - Quickly verify a build fix without full rebuild |
| 121 | - Debug static generation issues for specific pages |
| 122 | - Iterate faster on build errors |