Use --debug-prerender to see detailed build errors
Rerun the build with next build --debug-prerender to see more detailed error information when production builds minify server code and don't generate source maps. This flag disables minification, turns on source maps for server bundles, and continues past the first failure so remaining issues surface in one run. This helps identify issues thrown during prerendering. Do not deploy builds produced with --debug-prerender as they skip optimizations needed in production.
Use --debug-build-paths to build specific routes
Pass --debug-build-paths with the route files to include when building specific routes instead of rebuilding everything. The option accepts comma-separated paths and glob patterns, with a ! prefix to exclude, and combines with --debug-prerender while debugging. Next.js compiles and prerenders only the matching routes and skips the rest of the app.
Firefox Debugger extension required for VS Code
To use Firefox debugging in VS Code, you must install the Firefox Debugger extension from the Visual Studio Code marketplace.
Accessing VS Code Debug panel and starting debugging session
Go to the Debug panel using Ctrl+Shift+D on Windows/Linux or ⇧+⌘+D on macOS. Select a launch configuration, then press F5 or select 'Debug: Start Debugging' from the Command Palette to start your debugging session.
Debugging Next.js from a non-root directory
If running Next.js from a directory other than root (such as in a Turborepo monorepo), add 'cwd' property to the server-side and full stack debugging tasks. Example: 'cwd': '${workspaceFolder}/apps/web'.
JetBrains WebStorm debugging configuration
In JetBrains WebStorm, click the runtime configuration dropdown and select 'Edit Configurations...'. Create a JavaScript Debug configuration with http://localhost:3000 as the URL. Customize the browser and other settings as needed, then click OK. Running this configuration will automatically open the selected browser in debug mode, giving you two debug applications: the Next.js node application and the client/browser application.
Client-side debugging with Firefox DevTools
Start the development server with next dev, npm run dev, or yarn dev. Open http://localhost:3000 in Firefox. Open Firefox's Developer Tools with Ctrl+Shift+I on Windows/Linux or ⌥+⌘+I on macOS. Go to the Debugger tab. Code execution pauses when reaching a debugger statement. Search for files with Ctrl+P on Windows/Linux or ⌘+P on macOS, or use the file tree in the left panel. Source files appear with paths starting with webpack://_N_E/./
React Developer Tools browser extension
Install the React Developer Tools browser extension for React-specific debugging. This tool allows you to inspect React components, edit props and state, and identify performance problems.
Server-side debugging with --inspect flag
Pass the --inspect flag to debug server-side Next.js code with browser DevTools. Commands: pnpm dev --inspect, npm run dev -- --inspect, yarn dev --inspect, or bun run dev --inspect. The Node.js process will output 'Debugger listening on ws://127.0.0.1:9229/{id}' to the terminal.
Remote debugging with --inspect=0.0.0.0
Use --inspect=0.0.0.0 to allow remote debugging access outside localhost, such as when running the app in a Docker container.
Chrome server-side debugging via chrome://inspect
To debug server-side code in Chrome after starting with --inspect: Open a new tab and visit chrome://inspect. Look for your Next.js application in the Remote Target section. Click inspect to open a separate DevTools window. Go to the Sources tab. Source files have paths starting with webpack://{application-name}/./ where {application-name} comes from your package.json.
Firefox server-side debugging via about:debugging
To debug server-side code in Firefox after starting with --inspect: Open a new tab and visit about:debugging. Click This Firefox in the left sidebar. Under Remote Targets, find your Next.js application. Click Inspect to open the debugger. Go to the Debugger tab. Source files have paths starting with webpack://{application-name}/./ where {application-name} comes from your package.json.
Using --inspect-brk or --inspect-wait requires NODE_OPTIONS
To use --inspect-brk or --inspect-wait, specify NODE_OPTIONS environment variable instead of passing the flag directly. Example: NODE_OPTIONS=--inspect-brk next dev
Inspecting server errors with browser DevTools
When an error occurs, Next.js displays a Node.js icon underneath the Next.js version indicator on the error overlay. Click that icon to copy the DevTools URL to your clipboard. Open a new browser tab with that URL to inspect the Next.js server process and trace the root cause of errors.
Windows Defender impact on Next.js development
Ensure Windows Defender is disabled on Windows machines during Next.js development. Windows Defender checks every file read, which greatly increases Fast Refresh time with next dev. This is a known issue not related to Next.js but affects Next.js development.
Node.js debugger compatibility with Next.js
Any debugger that can attach to Node.js can also be used to debug a Next.js application. See the Node.js Debugging Guide for more details.
Package manager options for dev command
npm run dev can be replaced with yarn dev if using Yarn or pnpm dev if using pnpm.
Changing port number in debugger configuration
If changing the port number your application starts on, replace the 3000 in http://localhost:3000 with the port you are using in the debugger configuration.
VS Code launch.json configuration for Next.js debugging
Create a `.vscode/launch.json` file at the root of your project with four configurations: 'Next.js: debug server-side' (type: node-terminal, command: npm run dev -- --inspect), 'Next.js: debug client-side' (type: chrome, url: http://localhost:3000), 'Next.js: debug client-side (Firefox)' (type: firefox, url: http://localhost:3000, with reAttach: true and pathMappings for webpack://_N_E), and 'Next.js: debug full stack' (type: node, program: ${workspaceFolder}/node_modules/next/dist/bin/next, runtimeArgs: ['--inspect'], with serverReadyAction configuration). The full stack configuration uses serverReadyAction.action set to 'debugWithEdge' by default, or change to 'debugWithChrome' for Chrome.
Generate Turbopack trace file
To generate a Turbopack trace file, run `pnpm dev --internal-trace` (pnpm), `npm run dev -- --internal-trace` (npm), `yarn dev --internal-trace` (yarn), or `bun dev --internal-trace` (bun). Navigate around your application or make edits to reproduce the problem, then stop the Next.js development server. A file called `trace-turbopack.bin` will be available in the `.next-profiles` folder.
Enable detailed fetch logging with logging.fetches
Use the `logging.fetches` option in your `next.config.js` file to see more detailed information about what's happening during development. Set `logging.fetches.fullUrl` to `true` to see full URLs.
Turbopack tracing for performance analysis
Turbopack tracing is a tool that helps you understand the performance of your application during local development. It provides detailed information about the time taken for each module to compile and how they are related.
Interpret Turbopack trace file
To interpret a Turbopack trace file, use `npx next internal trace .next-profiles/trace-turbopack.bin`. On versions where `trace` is not available, use `npx next internal turbo-trace-server .next-profiles/trace-turbopack.bin`. Once the trace server is running, view the trace at https://trace.nextjs.org/. By default the trace viewer will aggregate timings; switch from "Aggregated in order" to "Spans in order" at the top right to see each individual time.
Add project folder to Windows Defender exclusions
On Windows, to add your project to the Microsoft Defender Antivirus exclusion list: Open the "Windows Security" application, select "Virus & threat protection" > "Manage settings" > "Add or remove exclusions". Add a "Folder" exclusion by selecting your project folder.
Disable Gatekeeper on macOS for development
On macOS, you can disable Gatekeeper inside of your terminal by running `sudo spctl developer-mode enable-terminal`. Then open the "System Settings" app, select "Privacy & Security" > "Developer Tools", ensure your terminal is listed and enabled (add third-party terminals like iTerm or Ghostty if using those), and restart your terminal.
next build --experimental-debug-memory-usage prints memory info during build
Starting in v14.2.0, you can run next build --experimental-debug-memory-usage to run the build in a mode where Next.js prints information about memory usage continuously throughout the build, including heap usage and garbage collection statistics. Heap snapshots are taken automatically when memory usage gets close to the configured limit. This feature is not compatible with the Webpack build worker option which is auto-enabled unless you have a custom webpack config.
SIGUSR2 signal triggers heap snapshot in debug memory usage mode
Starting in v14.2.0, when running next build with the --experimental-debug-memory-usage flag, you can send a SIGUSR2 signal to the process at any point and the process will take a heap snapshot. The heap snapshot will be saved to the project root of the Next.js application and can be loaded in any heap analyzer, such as Chrome DevTools, to see what memory is retained. This mode is not yet compatible with Webpack build workers.
NODE_OPTIONS=--inspect enables inspector for heap analysis
When running next build or next dev command, add NODE_OPTIONS=--inspect to the beginning of the command to expose the inspector agent on the default port. If you wish to break before any user code starts, you can pass NODE_OPTIONS=--inspect-brk instead. While the process is running, you can use a tool such as Chrome DevTools to connect to the debugging port to record and analyze a snapshot of the heap to see what memory is being retained.
Record heap profile with node --heap-prof
To look for memory issues, you can record a heap profile from Node.js by passing the --heap-prof flag to Node.js when starting your Next.js build: node --heap-prof node_modules/next/dist/bin/next build. At the end of the build, a .heapprofile file will be created by Node.js. In Chrome DevTools, you can open the Memory tab and click on the Load Profile button to visualize the file.
Use Lighthouse to measure Core Web Vitals
Lighthouse should be run in incognito mode to gain a better understanding of how users will experience the site and to identify areas for improvement. This is a simulated test and should be paired with looking at field data such as Core Web Vitals.
Turbopack tracing command in Next.js 16
The Turbopack tracing command should be: 'npx next internal trace .next-profiles/trace-turbopack.bin'
Development environment requires unsafe-eval for CSP
In development, 'unsafe-eval' must be enabled in CSP because React uses eval to provide enhanced debugging information, such as reconstructing server-side error stacks in the browser. 'unsafe-eval' is not required or used for production.
next-code-frame byte-level skip for long lines
When the visible window starts far into a long line (greater than 200 bytes from the line-level scan start), the heuristic additionally scans backwards from the visible start for a semicolon (;) and restarts the tokenizer there. This is critical for minified files where the entire source may be a single line, avoiding scanning hundreds of kilobytes of invisible content.
next-code-frame features
next-code-frame supports caller-provided output width (no terminal detection due to sans-io pattern), syntax highlighting for JS, TS, JSX, and TSX, graceful degradation for non-JS files or parsing errors, ANSI color support matching babel-code-frame aesthetics, and support for both single-line and multi-line error ranges.
next-code-frame purpose and design
next-code-frame is a Rust crate that provides fast, scalable code frame rendering for Next.js error reporting. It offers functionality similar to @babel/code-frame with improvements in scalability, long line handling, and syntax highlighting. The crate has no dependency on turbo-tasks, allowing use in webpack/rspack codepaths, is compilable to WASM, and follows sans-io patterns where the library accepts file content as arguments rather than performing IO.
next-code-frame CLI usage
The next-code-frame crate includes a code_frame binary for quick testing. Usage: cargo run -p next-code-frame --bin code_frame -- [filename] [start] [end] where positions are 1-indexed line:column format. Examples: cargo run -p next-code-frame --bin code_frame -- src/app.tsx 10:5 (single position), cargo run -p next-code-frame --bin code_frame -- src/app.tsx 10:5 10:20 (range), or cargo run -p next-code-frame --bin code_frame -- -m "Unexpected token" src/app.tsx 10:5 10:20 (with error message).
next-code-frame syntax highlighting tokenization
The highlighter uses a single compiled regex pass over visible content to tokenize strings, comments, numbers, regex literals, and identifiers. Keywords are identified via a compile-time perfect hash set (phf). Syntax highlighting is supported for JS, TS, JSX, and TSX with graceful degradation for non-JS files or parsing errors.
next-code-frame skip-scan heuristic for large files
For large files, the extract_highlights() function uses a skip-scan heuristic that walks backwards from the visible window looking for a blank line and starts the regex scan there. A blank line is a safe restart point for single-line constructs (strings, line comments, regex literals) because they cannot span blank lines. This avoids the expense of scanning from byte 0 where the regex tokenizer would dominate runtime.
next-code-frame skip-scan limitation with multi-line constructs
The skip-scan heuristic has a known limitation: it can produce incorrect highlighting when a multi-line construct (block comment or template literal) contains a blank line that falls between the scan start and the visible window. In this case the scanner misses the opening delimiter and the closing delimiter or trailing code may lose expected coloring. This is a deliberate tradeoff because blank lines inside block comments or template literals spanning window boundaries are rare in practice, and the consequence is only slightly wrong highlighting, never a failure or missing output.
next-code-frame byte-level skip limitation with strings
The semicolon skip heuristic has a known limitation: the semicolon can land inside a string literal, causing an unbalanced quote that cascades incorrect highlighting across the visible window. In practice minified code has frequent semicolons between statements so this rarely triggers, and the consequence is only incorrect highlighting, never a failure.
Adding error and warning links to Next.js messages
Next.js has a system to add helpful links to warnings and errors. This allows the logged message to be short while providing a broader description and instructions on how to solve the warning or error on the documentation. All warnings and errors added should have these links attached.
Creating new error links with pnpm new-error
To add a new error link, run the command 'pnpm new-error'. This command will create the error document and automatically update the manifest. At the end of the command execution, the URL for the error will be provided, which should then be added to your error.