---
title: "Cache Miss Route Fetching"
description: "The execution flow starting from fetchRouteOnCacheMiss down to encodeCacheBustingSearchParam coordinates fetching prefetch route information when a segment cache miss occurs, and ensures network re..."
last_updated: "2026-10-12T06:38:56.872063+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/how-it-works/cache-miss-route-fetching"
---

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

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

- [packages/next/src/client/components/segment-cache/cache.ts](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/client/components/segment-cache/cache.ts)
- [packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts)
- [packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts)
</details>

## 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](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/client/components/segment-cache/cache.ts#L1825-L1846), [packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts:53-59](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts#L53-L59), [packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts:6-13](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts#L6-L13)

---

### 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](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/client/components/segment-cache/cache.ts#L1825-L1846)

---

### 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](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/client/components/segment-cache/cache.ts#L3663-L3698)

---

### 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](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts#L53-L59)

---

### 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](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts#L53-L59)

---

### 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](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts#L16-L34)

---

### 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](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts#L60-L77)

---

### 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](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts#L47-L58)

---

### 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](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts#L6-L13)

---

## Architectural Diagrams

### Sequence Diagram

```mermaid
sequenceDiagram
    participant Cache as cache.ts
    participant Reducer as set-cache-busting-search-param.ts
    participant Utils as cache-busting-search-param.ts

    Cache->>Cache: fetchRouteOnCacheMiss()
    Cache->>Cache: fetchPrefetchResponse()
    Cache->>Reducer: setCacheBustingSearchParam(url, headers)
    Reducer->>Reducer: computeClientCacheBustingSearchParam(headers)
    Reducer->>Utils: computeCacheBustingSearchParam(...)
    Utils->>Utils: computeCacheBustingSearchParamFromInput(input)
    Utils->>Utils: encodeCacheBustingSearchParam(bytes)
    Utils-->>Reducer: return hash string
    Reducer->>Reducer: setCacheBustingSearchParamWithHash(url, hash)
    Reducer-->>Cache: URL mutated with query parameter
```

Sources: [packages/next/src/client/components/segment-cache/cache.ts:1825-1846](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/client/components/segment-cache/cache.ts#L1825-L1846), [packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts:16-59](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts#L16-L59), [packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts:6-13](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts#L6-L13)

### Flowchart

```mermaid
flowchart TD
    A[Cache Miss] --> B[fetchRouteOnCacheMiss]
    B --> C[fetchPrefetchResponse]
    C --> D[setCacheBustingSearchParam]
    D --> E{Crypto API Available?}
    E -- Yes --> F[computeCacheBustingSearchParam]
    E -- No --> G[computeLegacyCacheBustingSearchParam]
    F --> H[computeCacheBustingSearchParamFromInput]
    H --> I[encodeCacheBustingSearchParam]
    I --> J[Append _rsc Hash to URL]
    G --> J
    J --> K[Execute HTTP Request]
```

Sources: [packages/next/src/client/components/segment-cache/cache.ts:1825-1846](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/client/components/segment-cache/cache.ts#L1825-L1846), [packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts:16-34](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts#L16-L34), [packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts:47-77](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/shared/lib/router/utils/cache-busting-search-param.ts#L47-L77)

---

## 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.

## Sitemap

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