fix: prevent duplicate RSC requests when navigation happens during inflight prefetch

[rosbitskyy]

What?

Fixed duplicate RSC requests when navigation happens while a prefetch is already in progress. Previously, when a user clicked a link quickly after prefetch started, navigation would immediately make a new RSC request instead of waiting for the inflight prefetch to complete.

Why?

When a prefetch has Pending status (request already in flight), the navigation logic was only checking for Fulfilled status. If the prefetch was still pending, navigation would fall through to navigateDynamicallyWithNoPrefetch, which immediately makes a new RSC request. This caused duplicate requests and wasted network bandwidth, especially when users clicked links quickly after prefetch was initiated.

How?

• Added promise field to PendingRouteCacheEntry to track navigation requests waiting for prefetch completion
• Created waitForRouteCacheEntry function (similar to waitForSegmentCacheEntry) that returns a promise resolving when the prefetch completes
• Updated fulfillRouteCacheEntry and rejectRouteCacheEntry to resolve the promise when prefetch completes or fails
• Modified navigate function to check for Pending status and wait for prefetch completion before making a new request
• Added e2e test to verify only one request is made when navigation happens during inflight prefetch

The implementation follows the same pattern already used for segment cache entries, ensuring consistency across the codebase.

Fixes #86400

[vercel]

Notifying the following users due to files changed in this PR based on this repo's notify modifiers:

@timneutkens, @ijjk, @shuding, @huozhi:

packages/next/src/server/config.ts

[ijjk]

Allow CI Workflow Run

• approve CI run for commit: 6a88ec2

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

[graphite-app]

Promise cleanup logic will never execute due to status check happening after mutation. After fulfilledEntry.status = EntryStatus.Fulfilled is set on line 932, the condition if (entry.status === EntryStatus.Pending) on line 944 will always be false since entry and fulfilledEntry reference the same object. This means pendingEntry.promise = null on line 946 never executes, causing a memory leak.

Fix by moving the cleanup before the status check or removing the redundant check:

if (promiseToResolve !== null) {
  promiseToResolve.resolve(fulfilledEntry)
  // Free the promise for garbage collection.
  const pendingEntry = entry as PendingRouteCacheEntry
  pendingEntry.promise = null
}

Suggested change

	if (promiseToResolve !== null) {
	promiseToResolve.resolve(fulfilledEntry)
	// Free the promise for garbage collection.
	if (entry.status === EntryStatus.Pending) {
	const pendingEntry = entry as PendingRouteCacheEntry
	pendingEntry.promise = null
	}
	}
	if (promiseToResolve !== null) {
	promiseToResolve.resolve(fulfilledEntry)
	// Free the promise for garbage collection.
	const pendingEntry = entry as PendingRouteCacheEntry
	pendingEntry.promise = null
	}

Spotted by Graphite Agent



Is this helpful? React 👍 or 👎 to let us know.

[vercel]

Suggested change

	if (entry.status === EntryStatus.Pending) {
	const pendingEntry = entry as PendingRouteCacheEntry
	pendingEntry.promise = null
	}
	const pendingEntry = entry as PendingRouteCacheEntry
	pendingEntry.promise = null

The promise cleanup code in fulfillRouteCacheEntry never executes because the entry status is already changed to Fulfilled before the check, causing a memory leak where promises are never cleared.

View Details

Analysis

Memory leak: Promise not cleared in fulfillRouteCacheEntry

What fails: The fulfillRouteCacheEntry function in packages/next/src/client/components/segment-cache/cache.ts (lines 944-947) never clears the promise from memory after resolving it, causing a memory leak.

How to reproduce:

1. Request a route prefetch that results in a Pending cache entry
2. Call fulfillRouteCacheEntry with that entry
3. The entry's promise is resolved but never set to null

Root cause: The code captures whether the entry is Pending at line 926-929, but then at line 932 changes the status to Fulfilled. When it later checks if (entry.status === EntryStatus.Pending) at line 944, the condition is always false because the status has already been changed to Fulfilled. This prevents the cleanup code pendingEntry.promise = null from executing, keeping the resolved promise object in memory indefinitely.

Fix: Since promiseToResolve is only set if the entry was Pending at the time of the first check (line 926), we can use promiseToResolve !== null as the condition to clear the promise, rather than checking the status a second time after it has already been changed to Fulfilled.

[codspeed-hq]

CodSpeed Performance Report

Merging #86700 will not alter performance

_{Comparing rosbitskyy:fix/prefetch-inflight-duplicate (6a88ec2) with canary (2cd70df)}

Summary

✅ 17 untouched
⏩ 3 skipped¹

Footnotes

1. 3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩