Skip to main content
doc0blade47/next.jsdocumentation home
Sign in

Cache Miss Route Fetching

Last updated Oct 12, 2026
Relevant source files

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

Overview

The execution flow starting from fetchRouteOnCacheMiss down to encodeCacheBustingSearchParam coordinates fetching prefetch route information when a segment cache miss occurs, and ensures network requests bypass CDNs that fail to respect custom router headers. By encoding key request headers into a compact query parameter (often _rsc), Next.js guarantees cache uniqueness across diverse hosting environments.

Sources: packages/next/src/client/components/segment-cache/cache.ts:1825-1846, packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts:53-59, packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts:6-13

Step 1: fetchRouteOnCacheMiss

When a route is requested and results in a cache miss, fetchRouteOnCacheMiss initializes headers specifying the RSC prefetch type and segment path (/_tree). It prepares the target URL for fetching the route tree structure.

Sources: packages/next/src/client/components/segment-cache/cache.ts:1825-1846

Step 2: fetchPrefetchResponse

Next, fetchPrefetchResponse executes the network call using underlying fetch utilities. It wraps request creation and configures prefetch priorities without instantly decoding the binary stream.

Sources: packages/next/src/client/components/segment-cache/cache.ts:3663-3698

Step 3: createFetch

createFetch coordinates the outbound HTTP request. Depending on CDN capabilities and environment parameters, it may invoke cache-busting mechanisms to decorate the outgoing request URL with query parameters derived from headers.

Sources: packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts:53-59

Step 4: setCacheBustingSearchParam

To handle static hosting providers and CDNs that ignore custom headers like Next-Router-Prefetch, setCacheBustingSearchParam computes a unique hash from the request headers and appends it to the URL query string.

Sources: packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts:53-59

Step 5: computeClientCacheBustingSearchParam

This function verifies whether the browser environment supports the modern Crypto API. If cryptographic digest operations are available via globalThis.crypto.subtle, it proceeds with the secure hashing path; otherwise, it falls back to a legacy hashing mechanism.

Sources: packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts:16-34

Step 6: computeCacheBustingSearchParam

computeCacheBustingSearchParam aggregates relevant prefetch headers (such as prefetch flags, segment prefetch identifiers, state tree paths, and next URLs) into a normalized input string before passing it down for digest computation.

Sources: packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts:60-77

Step 7: computeCacheBustingSearchParamFromInput

Using the Web Crypto API, this function computes a SHA-256 hash of the header input string. It truncates the resulting digest to a compact 96-bit window (12 bytes) to keep the generated _rsc search query short and clean.

Sources: packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts:47-58

Step 8: encodeCacheBustingSearchParam

Finally, encodeCacheBustingSearchParam takes the binary digest buffer, converts it to a standard base64 string, and replaces URL-unsafe characters (swapping + for -, / for _, and stripping padding = characters) to produce a safe cache-busting token.

Sources: packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts:6-13

Architectural Diagrams

Sequence Diagram

Sources: packages/next/src/client/components/segment-cache/cache.ts:1825-1846, packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts:16-59, packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts:6-13

Flowchart

Sources: packages/next/src/client/components/segment-cache/cache.ts:1825-1846, packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts:16-34, packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts:47-77

Key Observations

  • Cross-Module Boundaries: This execution path bridges high-level segment cache management (cache.ts), router action reducers (set-cache-busting-search-param.ts), and lower-level shared URL utilities (cache-busting-search-param.ts).
  • Resilience on Static CDNs: By hashing headers into a URL query parameter (_rsc), Next.js bypasses limitations on edge networks and proxies that strip custom routing headers or fail to evaluate Vary headers properly.
  • Graceful Fallbacks: The system checks for the presence of modern cryptographic APIs (globalThis.crypto.subtle) and smoothly falls back to legacy hashing strategies if needed, ensuring continuous operation across varied runtime runtimes.
Was this page helpful?
Powered by doc0