# Behavior traces — vercel/next.js

> Canonical page: https://codevetter.com/unpack/nextjs/behavior-traces

# Behavior traces — vercel/next.js

Scanned commit 2861a364fcbe75fe96b0b9127f9b335edfcf288c (2026-09-22). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

Three flows dominate the codebase. (1) Dev startup: CLI parse → fork → HTTP listen → router-server init → dev bundler → render server lazy init. (2) A production request: socket → header filtering → route resolution → `BaseServer.handleRequest` → route module render → response cache → pipe. (3) A production build: config load → route discovery → bundler compile → static generation → manifests → trace collection → adapter callback. Each is traceable through named functions, and each is instrumented with a `trace()`/OTEL span so the sequence is visible in `.next/trace`.
- Dev startup order: `bin/next.ts` checks the Node version against `__NEXT_REQUIRED_NODE_VERSION_RANGE` and exits 1 on mismatch, warns if `react`/`react-dom` fail `require.resolve`, stamps `NEXT_PRIVATE_START_TIME`, then runs the `dev` action. — [packages/next/src/bin/next.ts#L61-L90](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/bin/next.ts#L61-L90)
- `nextDev` then opens a `trace('next-dev')` session span, records a 'rage restart' if the previous session for this project dir stopped within `RAGE_RESTART_THRESHOLD_MS` (90s) using a shared `dev-state.json` keyed by project directory under the OS cache dir, and forks the child. — [packages/next/src/cli/next-dev.ts#L68-L100](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/cli/next-dev.ts#L68-L100) [packages/next/src/cli/next-dev.ts#L352-L400](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/cli/next-dev.ts#L352-L400)
- In the child, `startServer()` sets `process.title = 'next-server (v...)'`, creates the http(s) server with a `requestListener` that awaits `handlersPromise`, registers an `'upgrade'` handler that destroys the socket on error, and only afterwards calls `initialize()` to populate `requestHandler`/`upgradeHandler`. — [packages/next/src/server/lib/start-server.ts#L200-L292](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/lib/start-server.ts#L200-L292) [packages/next/src/server/lib/start-server.ts#L495-L505](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/lib/start-server.ts#L495-L505)
- `initialize()` runs `setupDevBundler({ ... renderServer ... })` inside a `setupDevBundlerSpan`, wraps the result in `new DevBundlerService(...)`, assigns `renderServer.instance = require('./render-server')`, builds `renderServerOpts`, sets `renderServerOpts.serverFields.routerServerHandler = requestHandlerImpl` (a deliberate back-reference), and awaits `renderServer.instance.initialize(renderServerOpts)`. — [packages/next/src/server/lib/router-server.ts#L206-L306](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/lib/router-server.ts#L206-L306) [packages/next/src/server/lib/router-server.ts#L917-L950](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/lib/router-server.ts#L917-L950)
- Only once handlers exist does the child `process.send({ nextWorkerReady: true })`; the parent replies with `nextWorkerOptions`, the child later sends `{ nextServerReady: true, port, distDir }`, and the parent stores `port` (for restart reuse) and `distDir` (for telemetry and trace upload). — [packages/next/src/server/lib/start-server.ts#L648-L673](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/lib/start-server.ts#L648-L673) [packages/next/src/cli/next-dev.ts#L434-L452](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/cli/next-dev.ts#L434-L452)
- Dev restart is signalled by exit code: `requestListener`'s `finally` block calls `getMemoryRestartStats()` and, when near the heap limit, emits a `server-restart-close-to-memory-threshold` span, flushes traces and `process.exit(RESTART_EXIT_CODE)`; the parent sees that code, uploads the existing `.next/trace` before it is overwritten, and restarts. — [packages/next/src/server/lib/start-server.ts#L253-L270](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/lib/start-server.ts#L253-L270) [packages/next/src/cli/next-dev.ts#L457-L475](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/cli/next-dev.ts#L457-L475)
- Request trace (dev): `requestHandlerImpl` → `filterInternalHeaders` → request-insights endpoint check → i18n `getLocaleRedirect` → optional `compress()` with a `res.once('close')` hook calling `releaseCompressionStream` to avoid a zlib leak on client disconnect → `handleRequest(0)`, which first calls `blockCrossSiteDEV`. — [packages/next/src/server/lib/router-server.ts#L307-L420](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/lib/router-server.ts#L307-L420) [packages/next/src/server/lib/router-server.ts#L490-L500](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/lib/router-server.ts#L490-L500)
- `handleRequest(handleIndex)` is recursive with a hard stop — it throws `Attempted to handle request too many times` once `handleIndex > 5` — and `invokeRender` re-enters it at `handleIndex + 1` when the render server throws `NoFallbackError`. — [packages/next/src/server/lib/router-server.ts#L470-L500](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/lib/router-server.ts#L470-L500)
- Render trace: `BaseServer.handleRequest` → `await this.prepare()` → `tracer.withPropagatedContext(req.headers, ...)` → `tracer.trace(BaseServerSpan.handleRequest, ...)` → `handleRequestImpl`, with the span renamed in `.finally()` to `RSC GET /route` or `GET /route` from `next.route`, and `http.route` propagated up to a platform-created parent span for APM tools. — [packages/next/src/server/base-server.ts#L866-L955](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/base-server.ts#L866-L955)
- When request insights are enabled the whole handler is additionally wrapped in `runWithRequestInsightsIdentity({ requestId, htmlRequestId, url }, handleRequest)`, taking the id from the `NEXT_REQUEST_ID_HEADER`/`NEXT_HTML_REQUEST_ID_HEADER` headers or minting one with `nanoid()`. — [packages/next/src/server/base-server.ts#L955-L980](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/base-server.ts#L955-L980)
- `handleRequestImpl` normalises before routing: it calls `patchSetHeaderWithCookieSupport` so middleware-set cookies survive API routes/`getServerSideProps`, then 308-redirects any URL matching `/(\\|\/\/)/` through `normalizeRepeatedSlashes`. — [packages/next/src/server/base-server.ts#L982-L1000](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/base-server.ts#L982-L1000)
- Page resolution: `NextNodeServer.findPageComponents` → `loadComponents({...})` reads the pages manifest and returns a `ComponentMod`; the corresponding `RouteModule` subclass then runs, e.g. `AppPageRouteModule.render()` → `renderToHTMLOrFlight()`. — [packages/next/src/server/next-server.ts#L837-L910](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/next-server.ts#L837-L910) [packages/next/src/server/route-modules/app-page/module.ts#L158-L185](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/server/route-modules/app-page/module.ts#L158-L185)
- Build trace: `build()` → `trace('next-build')` → load env files → resolve `NextConfigComplete` → `setAttribute('bundler', ...)` → `loadCustomRoutes` → create distDir → `discoverRoutes` → `createPagesMapping` → write `ROUTES_MANIFEST` → bundle → static generation → `writePrerenderManifest` → `printTreeView` → `telemetry.flush()`. — [packages/next/src/build/index.ts#L1098-L1310](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/build/index.ts#L1098-L1310) [packages/next/src/build/index.ts#L1477-L1710](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/build/index.ts#L1477-L1710) [packages/next/src/build/index.ts#L4454-L4765](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/build/index.ts#L4454-L4765)
- Webpack builds can be offloaded: when `experimental.webpackBuildWorker` is enabled the build sets a `use-build-worker` span attribute and runs `webpackBuild(useBuildWorker, [...])` in a worker exposing `collectBuildTraces`; Turbopack instead goes through a single `turbopackBuild(telemetry)` call. — [packages/next/src/build/index.ts#L1775-L1885](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/build/index.ts#L1775-L1885)
- Static export is a nested build stage: `build()` `require`s `../export` and calls `exportApp(...)` twice — once for `output: 'export'` full static output (`writeFullyStaticExport`) and once for per-page static generation — before manifests are finalised. — [packages/next/src/build/index.ts#L1014-L1022](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/build/index.ts#L1014-L1022) [packages/next/src/build/index.ts#L3114-L3270](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/build/index.ts#L3114-L3270) [packages/next/src/export/index.ts](https://github.com/vercel/next.js/blob/2861a364fcbe75fe96b0b9127f9b335edfcf288c/packages/next/src/export/index.ts)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)