---
title: "Instant Validation"
description: "Instant validation provides a compile-time and development-time verification mechanism for Next.js App Router applications to ensure that routes configured with instant navigation or static optimiz..."
last_updated: "2026-09-23T10:52:03.167933+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/app-router-rendering/instant-validation"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [packages/next/src/server/app-render/instant-validation/instant-samples.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples.ts)
- [packages/next/src/server/app-render/app-render.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render.tsx)
- [packages/next/src/server/app-render/instant-validation/instant-validation.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation.tsx)
- [packages/next/src/server/app-render/instant-validation/instant-samples-client.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples-client.ts)
- [packages/next/src/server/app-render/instant-validation/instant-validation-error.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation-error.ts)
- [packages/next/src/server/lib/router-utils/typegen.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/lib/router-utils/typegen.ts)
- [packages/next/src/server/app-render/instant-validation/instant-config.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-config.tsx)
- [packages/next/src/server/request/params.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/request/params.ts)
- [packages/next/src/server/app-render/dynamic-rendering.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/dynamic-rendering.ts)
- [packages/next/src/server/request/search-params.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/request/search-params.ts)
- [packages/next/src/server/typescript/rules/config.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/typescript/rules/config.ts)
- [packages/next/src/server/app-render/instant-validation/boundary-constants.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/boundary-constants.ts)
- [packages/create-next-app/templates/app-api/ts/app/slug/route.ts](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app-api/ts/app/%5Bslug%5D/route.ts)
- [packages/create-next-app/templates/app-api/js/app/slug/route.js](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app-api/js/app/%5Bslug%5D/route.js)
- [packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-props/route-access-prop-01.output.tsx](https://github.com/blade47/next.js/blob/main/packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-props/route-access-prop-01.output.tsx)
- [packages/next/src/server/app-render/instant-validation/boundary-impl.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/boundary-impl.tsx)
- [packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-props/route-access-prop-01.input.tsx](https://github.com/blade47/next.js/blob/main/packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-props/route-access-prop-01.input.tsx)
- [packages/next/src/next-devtools/dev-overlay/components/instant/instant-guidance-data.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/dev-overlay/components/instant/instant-guidance-data.ts)
- [packages/create-next-app/templates/app-api/ts/app/route.ts](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app-api/ts/app/route.ts)
- [packages/create-next-app/templates/app-api/js/app/route.js](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app-api/js/app/route.js)
- [packages/create-next-app/templates/default/ts/pages/api/hello.ts](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default/ts/pages/api/hello.ts)
- [packages/next/src/client/components/client-page.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/client/components/client-page.tsx)
- [packages/next/src/server/app-render/manifests-singleton.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/manifests-singleton.ts)
- [packages/next/src/shared/lib/invariant-error.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/shared/lib/invariant-error.ts)
</details>

## Overview

Instant validation provides a compile-time and development-time verification mechanism for Next.js App Router applications to ensure that routes configured with instant navigation or static optimization requirements satisfy their expected parameter contracts, layout constraints, and boundary structures. By evaluating loader trees, simulating request contexts with synthetic samples, and tracking dynamic data access across server and client component boundaries, the system catches misconfigurations and missing inputs early, preventing runtime rendering failures and static generation bailouts.

Sources: [packages/next/src/server/app-render/instant-validation/instant-samples.ts:1-74](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples.ts#L1-L74), [packages/next/src/server/app-render/app-render.tsx:6533-6666](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render.tsx#L6533-L6666), [packages/next/src/server/app-render/instant-validation/instant-validation.tsx:1-46](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation.tsx#L1-L46), [packages/next/src/server/app-render/instant-validation/instant-config.tsx:1-51](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-config.tsx#L1-L51)

## Segment Configuration and Route Evaluation

### Overview

Analyzing loader trees determines instant validation eligibility and blocking rules across segment configurations in Next.js. The system inspects layouts and pages recursively to evaluate validation levels, runtime prefetch capabilities, and whether specific segments are permitted to block navigation or require static shells.

Sources: [packages/next/src/server/app-render/instant-validation/instant-config.tsx:53-109](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-config.tsx#L53-L109)

### Segment Configuration Evaluation Workflow

The loader tree evaluation engine follows a recursive traversal pattern across route segments, checking module exports and parallel route slots. The execution call chain operates through specific internal functions:

1. `anySegmentNeedsInstantValidation()` — Serves as the top-level orchestrator retrieving validation settings from the active `WorkStore`.
2. `visit()` — Recursively traverses the `LoaderTree` to extract layout or page modules via `getLayoutOrPageModule()`.
3. `isImplicitValidationSegment()` — Determines if unconfigured page or default segments qualify for implicit validation under non-manual default levels.
4. `isFrameworkErrorRoute()` — Evaluates whether a route corresponds to framework-synthesized error (`_not-found` or `_global-error`) entry points to exclude them from default validation.

Sources: [packages/next/src/server/app-render/instant-validation/instant-config.tsx:28-51](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-config.tsx#L28-L51), [packages/next/src/server/app-render/instant-validation/instant-config.tsx:126-224](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-config.tsx#L126-L224)

### Validation Levels and Disable Flags

Validation behavior is governed by configuration properties defined on segment configs and global work stores. The system maps validation options to internal execution flags and validation thresholds.

| Configuration / Constant | Type | Meaning / Purpose |
| :--- | :--- | :--- |
| `VALIDATION_LEVEL.WARNING` | Enum (`0`) | Dev-time validation threshold used in `anySegmentNeedsInstantValidationInDev`. |
| `VALIDATION_LEVEL.ERROR` | Enum (`1`) | Build-time validation threshold used in `anySegmentNeedsInstantValidationInBuild`. |
| `unstable_disableValidation` | Boolean | Disables validation globally for the entire loader tree when encountered on any segment config. |
| `unstable_disableDevValidation` | Boolean | Disables validation specifically during development runs when `level === VALIDATION_LEVEL.WARNING`. |
| `unstable_disableBuildValidation` | Boolean | Disables validation specifically during build runs when `level === VALIDATION_LEVEL.ERROR`. |
| `prefetch: 'allow-runtime'` | String | Indicates runtime prefetch configuration checked by `anySegmentHasRuntimePrefetchEnabled`. |

Sources: [packages/next/src/server/app-render/instant-validation/instant-config.tsx:53-77](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-config.tsx#L53-L77), [packages/next/src/server/app-render/instant-validation/instant-config.tsx:111-234](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-config.tsx#L111-L234)

> [!WARNING]
> Setting `unstable_disableValidation: true` on any segment config short-circuits the recursive visitor and completely aborts instant validation for the entire route tree, ignoring all other explicit opt-ins or implicit rules.

Sources: [packages/next/src/server/app-render/instant-validation/instant-config.tsx:168-193](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-config.tsx#L168-L193)

### Sample Resolution and Precedence

When resolving instant configuration samples for a page, inner segments override outer segments without performing merge logic. The `resolveInstantConfigSamplesForPage` function walks child trees along the `children` parallel route slot to collect sample definitions.

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| **Segment override without merging** | Predictable, isolated sample definitions per page or layout without deep object merging overhead. | Outer layout samples cannot be augmented by child pages; child definitions completely replace parent ones. |
| **Cache scoped to WorkStore** | Avoids redundant loader tree walks during a single request or render context. | Cache lifetime is strictly bound to the duration of the active `WorkStore`. |
| **Explicit framework error exclusion** | Prevents unintended validation failures on framework-managed error UI without user configuration. | Framework error routes require explicit user opt-in via `instant` configs if validation is desired. |

Sources: [packages/next/src/server/app-render/instant-validation/instant-config.tsx:46-51](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-config.tsx#L46-L51), [packages/next/src/server/app-render/instant-validation/instant-config.tsx:236-275](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-config.tsx#L236-L275)

## Synthetic Sample Generation and Tracking

### Overview

Synthetic sample parameters, cookies, and headers are generated and tracked during instant validation to simulate runtime access conditions. When dynamic values like cookies or route parameters are accessed without being declared in the configured sample data, the subsystem logs and throws errors using specialized tracking mechanisms.

Sources: [packages/next/src/server/app-render/instant-validation/instant-samples.ts:19-74](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples.ts#L19-L74)

### Sample Tracking and Error Execution

The sample tracking infrastructure inspects the active `workUnitAsyncStorage` store to locate and record missing sample access errors into an `InstantValidationSampleTracking` container. 

The validation tracking call chain operates through specific internal functions:
`getExpectedSampleTracking()` → retrieves the active store from `workUnitAsyncStorage` and branches on `workUnitStore.type` (accepting `'request'` or `'validation-client'`) → extracts `validationSampleTracking` or throws an `InvariantError` if missing → `trackMissingSampleError()` pushes the error to `missingSampleErrors` → `trackMissingSampleErrorAndThrow()` calls `trackMissingSampleError()` and then throws the `InstantValidationError`.

> [!NOTE]
> During validation store inspection, store types such as `'cache'`, `'prerender'`, and `'generate-static-params'` intentionally skip tracking retrieval, whereas any unhandled store type triggers a TypeScript exhaustive check (`workUnitStore satisfies never`).

Sources: [packages/next/src/server/app-render/instant-validation/instant-samples.ts:19-74](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples.ts#L19-L74), [packages/next/src/server/app-render/instant-validation/instant-validation-error.ts:1-17](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation-error.ts#L1-L17)

### Cookie and Search Parameter Generation

Cookies and search parameters are synthesized from sample configurations to construct proxy-wrapped request state. 

```typescript
export function createCookiesFromSample(
  sampleCookies: InstantSample['cookies'],
  route: string
): ReadonlyRequestCookies {
  const declaredNames = new Set<string>()

  const cookies = new RequestCookies(new Headers())
  if (sampleCookies) {
    for (const cookie of sampleCookies) {
      declaredNames.add(cookie.name)
      if (cookie.value !== null) {
        cookies.set(cookie.name, cookie.value)
      }
    }
  }

  const sealed = RequestCookiesAdapter.seal(cookies)

  return new Proxy(sealed, {
    get(target, prop, receiver) {
      if (prop === 'has') {
        const originalMethod = Reflect.get(target, prop, receiver)
        const wrappedMethod: typeof originalMethod = function (name) {
          if (!declaredNames.has(name)) {
            trackMissingSampleErrorAndThrow(
              createMissingCookieSampleError(route, name)
            )
          }
          return originalMethod.call(target, name)
        }
        return wrappedMethod
      }
      if (prop === 'get') {
        // ...
      }
    }
  })
}
```

Sources: [packages/next/src/server/app-render/instant-validation/instant-samples.ts:81-114](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples.ts#L81-L114)

Search parameters are parsed and built via `createURLSearchParamsFromSample`, iterating over configured entries and appending arrays or setting string values while ignoring `null` or `undefined` entries.

Sources: [packages/next/src/server/app-render/instant-validation/instant-samples.ts:390-407](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples.ts#L390-L407)

### Route Parameter Interpolation

Pathnames are generated from routes and sample parameters using `createPathnameFromRouteAndSampleParams`. The function splits the route by `/`, inspects each segment via `getSegmentParam`, and handles dynamic parameters, catch-all parameters, and static route segments.

| Segment Param Type | Handling Behavior | Error or Fallback |
| :--- | :--- | :--- |
| `catchall` / `optional-catchall` | Looks up `params[param.paramName]`, encodes array values. | Uses `[rawSegment]` as placeholder if undefined; throws `InstantValidationError` if value is not an array. |
| `dynamic` | Looks up `params[param.paramName]`, encodes string value. | Uses `rawSegment` as placeholder if undefined; throws `InstantValidationError` if value is not a string. |
| Intercepting route variants (`catchall-intercepted-*`, `dynamic-intercepted-*`) | Unsupported interception route validation. | Throws `InvariantError` with message `'Not implemented: Validation of interception routes'`. |
| Static segments | Appends raw segment directly to interpolated segments. | None. |

Sources: [packages/next/src/server/app-render/instant-validation/instant-samples.ts:414-478](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples.ts#L414-L478)

> [!CAUTION]
> Interception route parameters encountered during sample pathname interpolation immediately throw an `InvariantError` because validation for interception routes is not implemented.

Sources: [packages/next/src/server/app-render/instant-validation/instant-samples.ts:456-468](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples.ts#L456-L468)

### Root Parameter Assertion

The `assertRootParamInSamples` function checks whether a root parameter is defined within sample parameters. If the parameter is missing, it constructs and throws an `InstantValidationError` via `trackMissingSampleErrorAndThrow`.

Sources: [packages/next/src/server/app-render/instant-validation/instant-samples.ts:480-496](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples.ts#L480-L496)

## Client and Server Parameter Proxies

### Client and Server Parameter Proxies

Parameter and search parameter validation bridges client and server component boundaries by inspecting active work unit stores and wrapping underlying parameter collections in exhaustive proxy objects. These proxies check property access against declared keys from `unstable_samples` configurations, intercepting undeclared lookups to trigger validation errors.

Sources: [packages/next/src/server/app-render/instant-validation/instant-samples-client.ts:12-48](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples-client.ts#L12-L48), [packages/next/src/server/request/params.ts:644-657](https://github.com/blade47/next.js/blob/main/packages/next/src/server/request/params.ts#L644-L657)

### Client Parameter Instrumentation Walkchain

When validating client components, parameter helpers inspect the current execution environment and construct specialized wrappers. The instrumentation process follows a distinct call chain:

1. `instrumentParamsForClientValidation()` queries `workAsyncStorage` and `workUnitAsyncStorage` to obtain active stores.
2. It evaluates `workUnitStore.type`, matching against the `'validation-client'` unit type.
3. If `validationSamples` exist, it extracts declared parameter keys using `Object.keys(workUnitStore.validationSamples.params ?? {})`.
4. It calls `createExhaustiveParamsProxy()` with the underlying parameters, declared keys set, and route path to return the restricted parameter proxy.

Sources: [packages/next/src/server/app-render/instant-validation/instant-samples-client.ts:12-48](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples-client.ts#L12-L48)

> [!NOTE]
> If `workUnitStore` is not of type `'validation-client'` or contains no validation samples, `instrumentParamsForClientValidation` safely returns the unmodified `underlyingParams` reference without throwing.

Sources: [packages/next/src/server/app-render/instant-validation/instant-samples-client.ts:17-47](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples-client.ts#L17-L47)

### Fallback Route Parameters and Search Params

Client validation also verifies complete parameter coverage during specific expression evaluations. The helper function `expectCompleteParamsInClientValidation(expression)` checks fallback route parameters stored on validation client stores.

| Validation Function | Target Store Type | Action on Missing Declarations |
| :--- | :--- | :--- |
| `expectCompleteParamsInClientValidation` | `validation-client` | Calls `trackMissingSampleErrorAndThrow` with an `InstantValidationError` detailing missing fallback parameters. |
| `instrumentSearchParamsForClientValidation` | `validation-client` | Wraps `ReadonlyURLSearchParams` in an exhaustive search parameters proxy using declared sample keys. |
| `createServerParamsProxyForInstantValidation` | `request` / `validation` | Intercepts server-side `params` access using `createExhaustiveParamsProxy`. |

Sources: [packages/next/src/server/app-render/instant-validation/instant-samples-client.ts:50-87](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples-client.ts#L50-L87), [packages/next/src/server/app-render/instant-validation/instant-samples-client.ts:89-125](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-samples-client.ts#L89-L125), [packages/next/src/server/request/params.ts:644-657](https://github.com/blade47/next.js/blob/main/packages/next/src/server/request/params.ts#L644-L657)

## Validation Boundaries and Layout Markers

### Overview

Client validation boundaries and slot markers manage validation tracking and scope attribution across component trees and parallel layout slots. The implementation uses context providers, specialized boundary components, and namespace objects to ensure rendered validation IDs are tracked and errors are correctly attributed to their originating configuration.

Sources: [packages/next/src/server/app-render/instant-validation/boundary-impl.tsx:42-61](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/boundary-impl.tsx#L42-L61)

### Boundary Components and Tracking Call Chain

Validation boundaries interact with asynchronous storage to record rendered boundaries and prevent server bundle contamination. The validation boundary execution follows a strict call chain:

1. `InstantValidationBoundary` (accessed via `NameSpace`) invokes `getValidationBoundaryTracking()` during render.
2. `getValidationBoundaryTracking()` retrieves the store from `workUnitAsyncStorage.getStore()`.
3. It checks `store.type`, expecting `'validation-client'`, and returns `store.boundaryState`.
4. The boundary component calls `state.renderedIds.add(id)` to register that the boundary with identifier `id` successfully rendered.

Sources: [packages/next/src/server/app-render/instant-validation/boundary-impl.tsx:19-61](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/boundary-impl.tsx#L19-L61)

> [!CAUTION]
> Instant validation boundaries must never appear in browser bundles. Attempting to load `boundary-impl.tsx` when `typeof window !== 'undefined'` immediately throws an `InvariantError`.

Sources: [packages/next/src/server/app-render/instant-validation/boundary-impl.tsx:13-17](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/boundary-impl.tsx#L13-L17)

### Slot Markers and Stack Resolution

When a validation boundary spans multiple parallel slots, `SlotMarker` uses a cached dynamic component generator to render a marker matching `__next_instant_slot_N__`. During error handling, `resolveInstantStack` inspects the component stack using `slotMarkerRegex` to extract the slot index and retrieve the corresponding configuration stack.

Sources: [packages/next/src/server/app-render/dynamic-rendering.ts:780-807](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/dynamic-rendering.ts#L780-L807), [packages/next/src/server/app-render/instant-validation/boundary-impl.tsx:111-138](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/boundary-impl.tsx#L111-L138)

| Constant Name | Value | Purpose |
| :--- | :--- | :--- |
| `INSTANT_VALIDATION_BOUNDARY_NAME` | `__next_instant_validation_boundary__` | Component name identifier for instant validation boundaries in React stacks. |
| `INSTANT_SLOT_MARKER_PREFIX` | `__next_instant_slot_` | Prefix string for parallel layout slot marker components. |
| `INSTANT_SLOT_MARKER_SUFFIX` | `__` | Suffix string closing parallel layout slot marker components. |

Sources: [packages/next/src/server/app-render/instant-validation/boundary-constants.ts:1-6](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/boundary-constants.ts#L1-L6)

### Boundary Placement Design Trade-Offs

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| Namespace object for boundary name | Retains exact function name at runtime despite production minification | Requires string slice trick (`.slice(0)`) to prevent bundler inlining |
| Context-based placement (`PlaceValidationBoundaryBelowThisLevel`) | Automatically propagates boundary placement down layout trees without manual wrapping | Relies on router cooperation (`OuterLayoutRouter`) to render validation boundaries |
| Cached slot marker generator (`slotMarkerCache`) | Avoids dynamic component creation overhead across re-renders | Retains references to generated marker components in memory for the process lifetime |

Sources: [packages/next/src/server/app-render/instant-validation/boundary-impl.tsx:42-138](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/boundary-impl.tsx#L42-L138)

## Tree Depth Discovery and Serialization

### Overview

Tree depth discovery and segment serialization manage the structural traversal of route hierarchies, transforming initial React Server Component (RSC) payloads into segment paths, route trees, and stage-specific chunks.

Sources: [packages/next/src/server/app-render/instant-validation/instant-validation.tsx:1-46](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation.tsx#L1-L46)

### Segment Path Discovery and Route Trees

The segment validation planning phase relies on recursive tree traversal functions to map out `RouteTree` structures. `traverseRootSeedDataSegments` extracts root data from an `InitialRSCPayload` and delegates to `traverseCacheNodeSegments`, which processes segment nodes and parallel route children.

```typescript
function traverseRootSeedDataSegments(
  initialRSCPayload: InitialRSCPayload,
  processSegment: (
    segmentPath: SegmentPath,
    seedData: CacheNodeSeedData
  ) => void
) {
  const { flightRouterState, seedData } =
    getRootDataFromPayload(initialRSCPayload)

  const [rootSegment] = flightRouterState
  const rootPath = stringifySegment(rootSegment)
  return traverseCacheNodeSegments(
    rootPath,
    flightRouterState,
    seedData,
    processSegment
  )
}
```

Sources: [packages/next/src/server/app-render/instant-validation/instant-validation.tsx:109-127](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation.tsx#L109-L127)

Child segment paths are generated via `createChildSegmentPath`, which checks whether the parallel route key is `'children'` or a named parallel slot prefixed with `@`.

```typescript
function createChildSegmentPath(
  parentPath: SegmentPath,
  parallelRouteKey: string,
  segment: Segment
): SegmentPath {
  const parallelRoutePrefix =
    parallelRouteKey === 'children'
      ? ''
      : `@${encodeURIComponent(parallelRouteKey)}/`
  return `${parentPath}/${parallelRoutePrefix}${stringifySegment(segment)}` as SegmentPath
}
```

Sources: [packages/next/src/server/app-render/instant-validation/instant-validation.tsx:170-180](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation.tsx#L170-L180)

Segments are serialized into `SegmentPath` strings using `stringifySegment`, handling string segments by URI encoding them and array segments by encoding their components separated by pipe characters.

```typescript
function stringifySegment(segment: Segment): SegmentPath {
  return (
    typeof segment === 'string'
      ? encodeURIComponent(segment)
      : encodeURIComponent(segment[0]) + '|' + segment[1] + '|' + segment[2]
  ) as SegmentPath
}
```

Sources: [packages/next/src/server/app-render/instant-validation/instant-validation.tsx:182-188](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation.tsx#L182-L188)

> [!NOTE]
> If a segment key is a page segment (`__PAGE__`), search parameters may be appended. Consumers reading from the segment cache must ensure search parameters are correctly preserved and appended.

Sources: [packages/next/src/server/app-render/instant-validation/instant-validation.tsx:151-154](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation.tsx#L151-L154)

### Call-Chain Execution Walkthrough

The execution path for data collection and module resolution follows a strict sequence of calls through the rendering and manifests infrastructure:

1. `collectStagedSegmentData` initializes the staged chunk streams and triggers processing of component modules and manifests.
2. `getServerModuleMap` is called during stream operations to resolve module identifiers against the global manifests singleton.
3. `getManifestsSingleton` retrieves the underlying manifest singleton from `globalThis`, throwing an `InvariantError` if it has not been initialized.

```mermaid
sequenceDiagram
    participant collectStagedSegmentData as collectStagedSegmentData<br/>(instant-validation.tsx)
    participant getServerModuleMap as getServerModuleMap<br/>(manifests-singleton.ts)
    participant getManifestsSingleton as getManifestsSingleton<br/>(manifests-singleton.ts)

    collectStagedSegmentData->>getServerModuleMap: Requests server module mappings
    getServerModuleMap->>getManifestsSingleton: Accesses manifests singleton store
    getManifestsSingleton-->>getServerModuleMap: Returns ManifestsSingleton record
    getServerModuleMap-->>collectStagedSegmentData: Returns ServerModuleMap proxy
```

Sources: [packages/next/src/server/app-render/instant-validation/instant-validation.tsx:223-232](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation.tsx#L223-L232), [packages/next/src/server/app-render/manifests-singleton.ts:319-327](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/manifests-singleton.ts#L319-L327)

### Segment Stages and Types Reference

| Export Name | Type / Values | Purpose |
| :--- | :--- | :--- |
| `SegmentPath` | `string & { _tag: 'SegmentPath' }` | Branded string type identifying a unique route segment path. |
| `RouteTree` | Object (`path`, `segment`, `module`, `slots`) | Isomorphic structure to `FlightRouterState` augmented with instant configuration metadata. |
| `SegmentStage` | `RenderStage.Static`, `RenderStage.Runtime`, `RenderStage.Dynamic` | Enumerated stages that route segments can traverse during rendering. |
| `StageChunks` | `Record<SegmentStage, Uint8Array[]>` | Mapping of render stages to accumulated binary chunk arrays. |
| `StageEndTimes` | `RecordrefetchedSegmentStage, number>` | Timing records tracking when prefetched segment stages complete. |

Sources: [packages/next/src/server/app-render/instant-validation/instant-validation.tsx:88-107](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation.tsx#L88-L107), [packages/next/src/server/app-render/instant-validation/instant-validation.tsx:194-210](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation.tsx#L194-L210)

### Serialization and Traversal Design Trade-Offs

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| Stringified segment paths (`stringifySegment`) | Provides unique, cache-friendly string keys for tree lookups | Requires URI encoding and delimiter joining overhead per segment node |
| Global manifests singleton (`globalThis`) | Allows module-level server action and reference resolution without React context | Relies on global state mutation and explicit initialization order |
| Parallel route slot prefixing (`@slot/`) | Distinguishes parallel route branches cleanly within unified path strings | Lengthens path strings and requires special parsing rules for child segments |

Sources: [packages/next/src/server/app-render/instant-validation/instant-validation.tsx:170-188](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation.tsx#L170-L188), [packages/next/src/server/app-render/manifests-singleton.ts:19-36](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/manifests-singleton.ts#L19-L36)

## Build and Dev Validation Lifecycle

### Overview

The validation lifecycle manages the execution of asynchronous validation runs, processes validation errors, and handles diagnostics in development and build environments. Build-time validation relies on wrapper utilities that initialize custom contexts and execute sample-based renders.

Sources: [packages/next/src/server/app-render/app-render.tsx:6533-6559](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render.tsx#L6533-L6559)

### Build Validation Call Chain

The build-time validation sequence executes via a specific order of wrapper functions and context initializers:

1. `validateInstantConfigsInBuild` acts as the primary entry point, creating test log markers and delegating to `run()`.
2. `workAsyncStorage.exit` safely exits the outer work store scope before invoking `validateInstantConfigsInBuildImpl`.
3. `validateInstantConfigInBuildWithSample` initializes sample URLs, fallback parameters, and mock `WorkStore` and `AppRenderContext` structures.
4. `workAsyncStorage.run` executes the validation render within the isolated sample context.

```mermaid
sequenceDiagram
    participant validateInstantConfigsInBuild as validateInstantConfigsInBuild<br/>(app-render.tsx)
    participant workAsyncStorageExit as workAsyncStorage.exit<br/>(app-render.tsx)
    participant validateInstantConfigsInBuildImpl as validateInstantConfigsInBuildImpl<br/>(app-render.tsx)
    participant validateInstantConfigInBuildWithSample as validateInstantConfigInBuildWithSample<br/>(app-render.tsx)

    validateInstantConfigsInBuild->>workAsyncStorageExit: Exits outer work store context
    workAsyncStorageExit->>validateInstantConfigsInBuildImpl: Invokes build implementation
    validateInstantConfigsInBuildImpl->>validateInstantConfigInBuildWithSample: Processes each sample item
    validateInstantConfigInBuildWithSample-->>validateInstantConfigsInBuildImpl: Returns validation results
```

Sources: [packages/next/src/server/app-render/app-render.tsx:6533-6593](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render.tsx#L6533-L6593), [packages/next/src/server/app-render/app-render.tsx:6668-6785](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render.tsx#L6668-L6785)

### InstantValidationError Properties and Handling

The `InstantValidationError` class identifies exhaustive sample validation failures via a fixed string digest value.

| Export Name | Type / Value | Purpose |
| :--- | :--- | :--- |
| `INSTANT_VALIDATION_ERROR_DIGEST` | `'INSTANT_VALIDATION_ERROR'` | Constant string assigned to error digests for identification. |
| `isInstantValidationError` | `(err: unknown) => err is InstantValidationError` | Type guard verifying object type, `Error` instance, and matching digest. |
| `InstantValidationError` | Class extending `Error` | Custom error subclass carrying the validation error digest. |

Sources: [packages/next/src/server/app-render/instant-validation/instant-validation-error.ts:1-17](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/instant-validation-error.ts#L1-L17)

> [!WARNING]
> If `success` evaluates to false during `validateInstantConfigsInBuild`, the logs record an error and throw a `StaticGenBailoutError` to immediately halt the static prerender process.

Sources: [packages/next/src/server/app-render/app-render.tsx:6533-6559](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render.tsx#L6533-L6559)

## Related

- [Staged Dynamic Rendering](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/app-router-rendering/staged-dynamic-rendering)
- [Navigation Boundaries](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/client-routing/navigation-boundaries)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.