Next.js 16: Mismatch in RSC file paths causes 404 errors in static exports
Nobody has claimed this yet.
- 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
- Clone the reproduction repository
- Run
cd next16 - Run
npm install - Run
npm run build(output: 'export' is already set in next.config.ts) - Run
npx serve out - Visit
/next16in 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. - Run
cd .. - Run
cd next15 - 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=...').
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
- Reproducible Versions: Next.js 16.0.0 ~ 16.1.1
- This issue does not exist in Next.js 15
- This issue is reproducible locally using npx serve out and is also observed on static hosting platforms like GitHub Pages: https://aaakul.github.io/next16/ and Cloudflare Pages: https://next16-next-link-rsc-issue.pages.dev/
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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