vercel / vercel/next.js

Next.js 16: Mismatch in RSC file paths causes 404 errors in static exports

Open
#85,374 16 comments 12 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Linking and Navigating Output
Dominant language
JavaScript
Stars
142k
Forks
32.4k
Avg merge
2d 14h
Merged PRs (30d)
351

Description

Link to the code that reproduces this issue

https://github.com/Aaakul/next16-next-link-rsc-issue

To Reproduce
  1. Clone the reproduction repository
  2. Run cd next16
  3. Run npm install
  4. Run npm run build (output: 'export' is already set in next.config.ts)
  5. Run npx serve out
  6. Visit /next16 in a browser (e.g., http://localhost:3000/next16), open developer tools and check the console for 404 errors. Click the link to navigate to /next16/page, refresh and check if similar errors appears.
  7. Run cd ..
  8. Run cd next15
  9. Repeat 3~6
Current vs. Expected behavior

Current Behavior (Next.js 16.0.0 ~ 16.1.1 + output: 'export'):

When visiting static exported page has next/link with default prefetching or is explicitly set to true / "auto" / null, the page attempts to fetch the target page's RSC Payload from incorrect path, resulting in a 404 Not Found error (e.g., '.../page/__next.page.PAGE.txt?_rsc=...').
Image

Expected Behavior (Next.js 15.5.6 + output: 'export'):

Invalid RSC requests are not expected in statically exported pages

Provide environment information
Operating System:
  Platform: win32
  Arch: x64
  Version: Windows 10 Home
  Available memory (MB): 32578
  Available CPU cores: 16
Binaries:
  Node: 20.19.5
  npm: 10.8.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 16.0.1
  eslint-config-next: N/A
  react: 19.2.0
  react-dom: 19.2.0
  typescript: 5.9.3
Next.js Config:
  output: export
Which area(s) are affected? (Select all that apply)

Linking and Navigating, Output

Which stage(s) are affected? (Select all that apply)

next build (local), Other (Deployed)

Additional context

According to Axiorema's blog and this Next.js pull request, the problem comes from a big change in Next.js 16. This change affects how React Server Component (RSC) data is loaded. Even if you don’t use the new "Cache Components" feature, it still changes the way RSC data is handled.

The main issue is a mismatch between the file paths created during the build process and the file paths the browser looks for:

  • During the build, the file might be saved in a folder like __next/page/__PAGE__.txt.
  • But the browser tries to find the file with a name like __next.page.__PAGE__.txt.
Workaround

To fix this, you can use a build adapter, which is explained in Axiorema's blog: The Workaround: A Build Adapter.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked reproduction repository, compare the next15 and next16 examples, and inspect the generated out directory after npm run build with output: export. Use npx serve out and the browser console to trace the RSC request paths from next/link. Done means static exports no longer request mismatched paths or produce 404 errors, while the next15 behavior remains unaffected.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, next.js, react
Domain
build-system, web-dev
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.