Debugging, Instrumentation & Observability

Create .vscode/launch.json at the project root. The official guide gives one configuration for the server, one for the browser and one that starts both:

Pick a configuration in the Run and Debug panel (Ctrl+Shift+D, or Shift+Cmd+D on macOS) and press F5. Details from the guide:

Source: Next.js: Debugging

next dev --inspect and next start --inspect pass the flag to the underlying Node.js process. With npm run dev — --inspect the terminal reports the debugger address, and with a custom address the guide’s --inspect=host:port form works as in Node.js. This was the output of the dev server started on a scratch port, and the inspector answered on its HTTP endpoint (--inspect=127.0.0.1:9805 was used here to keep it off the default port 9229; the <id> is a per-run UUID):

next start --inspect=127.0.0.1:9805 printed the same Debugger listening and - Debugger port: 9805 lines, so the inspector is also available for a production build running locally. When I pinned a custom host:port to a dev server, a second Starting inspector on 127.0.0.1:9805 failed: address already in use line appeared (a worker process trying the same address) while the main process kept listening; the plain --inspect, which lets Node.js pick its default, avoids the noise.

Two flags need a different spelling. --inspect-brk (pause on the first line) and --inspect-wait cannot be passed to next dev directly; the guide says to set NODE_OPTIONS instead, as in NODE_OPTIONS=--inspect-brk next dev. The CLI reference shows the general form (NODE_OPTIONS='--inspect' next).

The inspector is remote code execution by design: anyone who can reach the port can run arbitrary JavaScript in your server process. --inspect=0.0.0.0, which the guide mentions for containers, is for a development container behind a port mapping bound to localhost, never for a shared network or a production host.

Source: Debugging: server-side code, next CLI: passing Node.js arguments, Node.js: Debugging guide

For client code, run next dev, open the page and open the browser DevTools: the Sources tab in Chrome, the Debugger tab in Firefox. A debugger statement pauses there, and Ctrl+P (or Cmd+P) searches files so you can set breakpoints by hand; client sources are under webpack://_N_E/./.

For server code, open chrome://inspect in Chrome (or about:debugging and This Firefox in Firefox) while the server runs with --inspect, find the Next.js process under Remote Target and click inspect. Server sources are listed under webpack://<application-name>/./, where the name comes from your package.json. When the error overlay appears for a server error, a Node.js icon under the version label copies the DevTools URL of the server process to your clipboard; open it in a new browser tab to inspect the process that failed. The overlay, the route indicator and the other development UI are described on Getting Started.

Install the React Developer Tools extension for the component tree, props and state, and profiling. On Windows, the guide recommends disabling Windows Defender scanning of the project: it checks every file read and slows Fast Refresh.

Source: Debugging: browser DevTools, React: React Developer Tools

Errors that appear only in next build are harder, because production builds minify server code. Three flags exist for that, and a prerender failure shows what they change. This page throws while prerendering a static route (the file was removed afterwards):

next build stops with the frame in the right file and line, but the stack names are anonymous:

With next build --debug-prerender the server code is not minified, server source maps are generated, and the build continues after the first error so you see every failing page at once:

The function names (loadPrice, Page) are back. The docs warn not to deploy a build made with this flag.

Source: next CLI: debugging prerender errors, Building: debugging build errors, prerender-error, productionBrowserSourceMaps

An error thrown while rendering a Server Component reaches the browser stripped of its message in production, so that server details do not leak; what travels is a digest, a hash that also appears next to the full error in the server log. To debug a production error, copy the digest from the browser (or from your error tracker) and search the server logs for it. Hydration mismatches, the most common client-only error, show in development a diff in the overlay that labels each differing line as coming from the client or the server (added in 16.2); the concept is covered on Hydration. In production the same mismatch is reported as a minified React error number: in the Server Action experiment below the browser’s window error listener received Minified React error #441, and the number resolves at react.dev/errors/441.

next dev (16 or later) serves an MCP endpoint at /_next/mcp. The next-devtools-mcp package is the bridge: it discovers running dev servers (several, on different ports), forwards tool calls to the right one and presents a single interface to the agent. Register it in the .mcp.json file at the project root, the format the official guide gives:

Start npm run dev; MCP-compatible agents then connect on their own. If they do not, check that the project is on Next.js 16 or later, that the config is loaded and restart the dev server. The guide lists these tools:

The endpoint is plain JSON-RPC over HTTP, which makes it checkable without an agent. This is a dev server on the scratch port answering the MCP handshake and the route tool (the get_routes result, whose entries are the Bookshelf routes of the scratch app, is shortened):

In 16.3.8 tools/list returned nine tools: the eight above (with get_compilation_issues and compile_route counted separately) plus get_request_insights, whose description says it needs the experimental.requestInsights option and which is not documented in the guide; treat it as experimental. A request that carried an Origin header of an unrelated site (http://evil.example) was answered with HTTP 403, so a web page cannot simply talk to your local MCP endpoint; plain curl without an Origin works, because it is a local process on your machine.

The practical rules follow from that: the MCP server shows your agent source-mapped stack traces and logs, so install next-devtools-mcp in projects where you want agents to look at the running app, do not expose a dev server on a shared network, and review what an agent changes as you would any other contribution. The same goes for the browser tooling the guide mentions (Playwright MCP integration).

Source: Next.js: Next.js MCP Server, vercel/next-devtools-mcp

Models answer from training data, and Next.js changed a lot in 15 and 16 (async request APIs, proxy.ts, cacheComponents). The framework therefore ships its own documentation inside the next package and tells agents to read it:

The agent guide also lists Skills for multi-step work (next-dev-loop, next-cache-components-adoption, next-cache-components-optimizer), which agents install with npx skills add; they package workflows, not framework knowledge. Treat third-party skills like third-party code and read them before installing.

Source: Next.js: AI Coding Agents, Next.js 16.2

register is called once when a new Next.js server instance starts and must finish before the server handles requests; it can be async. Use it to start an SDK (OpenTelemetry, an error tracker) before any application code runs. Anything slow here delays readiness, and an error thrown here stops the server from starting, so keep it small and make optional integrations fail soft.

onRequestError is called whenever the server captures an error, so you can forward it to an error tracker. error is typed unknown (narrow it before reading message or digest); when React processed the error during Server Component rendering it may not be the instance you threw, and the digest identifies it. Await any async work inside the handler. The example registers both functions, records the fields that are useful and deliberately does not forward request.headers, which would copy cookies and authorization headers to a third party:

Source: instrumentation.js, Instrumentation

Three failing endpoints exercise it: a Route Handler that throws, a Server Component that calls await connection() and throws (so it renders per request), and a Server Action invoked from a form. After next build and next start the server log showed the single register line at startup and one onRequestError line per failure (digests redacted):

A Pages Router project works the same way. In the second scratch project a getServerSideProps that throws produced "routerKind":"Pages Router","routePath":"/fail","routeType":"render".

The documentation additionally lists a renderType field ('dynamic' or 'dynamic-resume', the latter for Partial Prerendering). In 16.3.8 the shipped type RequestErrorContext does not declare it: reading context.renderType failed next build with Property 'renderType' does not exist on type 'Readonly<RequestErrorContext>'. Do not rely on it until the type and the docs agree.

instrumentation.ts is bundled for both runtimes, so libraries that need Node.js APIs must not be imported at the top of the file. Branch on process.env.NEXT_RUNTIME and import dynamically; the example in the official reference imports ./register.edge or ./register.node this way, and the OpenTelemetry section below uses the same shape. proxy.ts runs on Node.js in version 16, so most apps only meet the Edge runtime for the routes that opt into it.

Source: Execution timing, instrumentationClientInject

The @vercel/otel package configures the SDK for you and works in the Node.js and Edge runtimes, on Vercel and self-hosted. Install it with the peer packages the guide lists (@opentelemetry/sdk-logs, @opentelemetry/api-logs, @opentelemetry/instrumentation), then register it in instrumentation.ts:

Source: OpenTelemetry: using @vercel/otel

The console exporter is for learning; in production you omit traceExporter and point the OTLP exporter at your collector with the standard environment variables, with the values coming from your secret store and not from the repository:

A request to the /api/books-traced route handler of the next example, with this registration, printed the spans of resolve page components, bookshelf.search (ours), executing api route (app) /api/books-traced, start response and the root GET /api/books-traced, all with the same trace ID and with attributes such as next.route, next.span_type and a resource carrying service.name: 'bookshelf-web'.

When @vercel/otel does not cover a need (custom processors, a particular SDK feature), configure NodeSDK yourself. NodeSDK is not compatible with the Edge runtime, so import it only when NEXT_RUNTIME is nodejs, from a separate file. If you need the Edge runtime, you must stay with @vercel/otel.

Install @opentelemetry/sdk-node, @opentelemetry/resources, @opentelemetry/semantic-conventions, @opentelemetry/sdk-trace-node and @opentelemetry/exporter-trace-otlp-http. Two differences from the official example, both deliberate: it passes spanProcessor with a SimpleSpanProcessor, while @opentelemetry/sdk-node 0.222 marks spanProcessor as deprecated in favour of the spanProcessors array (the example uses it), and a BatchSpanProcessor exports in batches instead of one request per span, which is what production wants (the simple processor is useful for demos). The official example also imports ./instrumentation.node.ts with the extension; the extension-less import above built without any TypeScript setting.

Verification used a throw-away OTLP/HTTP receiver on 127.0.0.1:4318 (a 20-line Node.js script that printed the span names of each POST to /v1/traces) and OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 for next start. After two requests it printed one POST of about 7.7 KB with the spans below, parent=no marking the root:

Source: OpenTelemetry: manual configuration

Next.js creates the request, route and fetch spans; add your own for business operations with the @opentelemetry/api package. Unlike the official sketch, the example below records failures on the span and ends it in finally, and it stores the length of the query rather than the query, because attributes travel to a third party:

Calling curl "localhost:3805/api/books-traced?q=dune" returned [{"id":"1","title":"Dune",…​}], and the span bookshelf.search appeared in the trace with parent executing api route (app) /api/books-traced and attributes bookshelf.query_length: 4 and bookshelf.result_count: 1. register runs before your code in a new environment, so spans created in route code are attached to the exported trace.

Source: OpenTelemetry: custom spans, OpenTelemetry JavaScript

Attributes follow the OpenTelemetry semantic conventions, and Next.js adds its own under the next namespace: next.span_name, next.span_type, next.route, next.rsc (an RSC request such as a prefetch) and next.page (an internal identifier of a special file; only unique together with next.route). By default only some of the spans are exported; set NEXT_OTEL_VERBOSE=1 to emit more. With it, one visit to a book page and one to the catalogue added spans such as LoadComponents.loadComponents, BaseServer.render, AppRender.renderToReadableStream, AppRender.waitShellReady, NextServer.getRequestHandler and build component tree; that is useful in a performance investigation and noisy and costly as a permanent setting. A request that goes through the Proxy also emits a middleware GET span.

To test locally you need a collector with a backend; the guide recommends its OpenTelemetry dev environment, where the root span is labelled like GET /requested/pathname with all other spans nested under it. On Vercel, OpenTelemetry works out of the box and the platform documentation explains how to connect a provider; self-hosted deployments run their own OpenTelemetry Collector and point the exporter at it (the deployment itself is a topic of the deployment page of this section).

Source: OpenTelemetry: default spans, OpenTelemetry observability primer

The logging option in next.config controls what next dev prints to the terminal. It never affects production builds. It has five parts, and logging: false turns the dev logging off entirely:

Source: next.config.js: logging

A server page that fetches the catalogue API and a client button that calls console.log and console.warn, loaded and clicked in headless Chrome against next dev, gave this terminal output (the health endpoint, requested earlier, is absent because ignore matched it; the long React hydration-warning text that also appeared in this run is omitted):

The timings split each request into Next.js work, the Proxy, parameter generation and your code, which is the first place to look when a page is slow in development. fullUrl shows the complete fetch URL beneath the page line, together with the cache decision. Mind what you forward: a full URL or a browser console line can contain a token or personal data, and these are developer terminals, not log files to ship.

logging is a development convenience. In production the server writes whatever your code and Next.js write to standard output and standard error, which is where containers and platforms collect it. Practical rules that follow: log structured lines (one JSON object per line) with a level, the route and a request or trace identifier; log the digest of an error so the log line matches what the browser saw; never log request bodies, cookies, authorization headers or tokens; and prefer to send errors through onRequestError and traces through OpenTelemetry instead of parsing console output. Any logging library works in the Node.js runtime; avoid Node-only libraries in code that proxy.ts or Edge routes import. How a log pipeline stores and queries the lines is outside Next.js; see the Django logging and error reporting page and the Spring Boot and Quarkus pages named above for the conventions that carry over.