nextjs - ✅(Solved) Fix [Bug] Interception routes break on every HMR save in Next.js 16 — "Invalid interception route" error [1 pull requests, 3 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
vercel/next.js#91265Fetched 2026-04-08 00:42:01
View on GitHub
Comments
3
Participants
2
Timeline
9
Reactions
0
Author
Participants
Timeline (top)
commented ×2labeled ×2subscribed ×2cross-referenced ×1

Error Message

Error: Invalid interception route: /users/(.)(.)(.)1 Must be in the format /<intercepting route>/(..|...|..)(..)/<intercepted route>

Root Cause

Root Cause (investigated): In setup-dev-bundler.js, interception routes are pushed into beforeFiles on every HMR update without clearing old entries:

// Runs on EVERY HMR update — never clears!
opts.fsChecker.rewrites.beforeFiles.push(...interceptionRoutes); // BUG

Fix Action

Fixed

PR fix notes

PR #91364: fix(dev): clear stale interception rewrites on HMR update to prevent accumulation

Description (problem / solution / changelog)

What

Fixes interception routes breaking on every HMR file save in Next.js 16.

Why

In setup-dev-bundler.ts, interception route rewrites are pushed into beforeFiles on every HMR aggregated event without clearing old entries first. The (.) markers stacking up on every save makes dev pretty painful since you have to do a full refresh each time. This causes entries to accumulate on every save:

  • Save No.1 → [(.)users/[id]]
  • Save No.2 → [(.)users/[id], (.)users/[id]]
  • Save No.3 → [(.)users/[id], (.)users/[id], (.)users/[id]]

The duplicate rewrites corrupt pathname matching, producing paths like /users/(.)(.)(.)1, which then throws:

Error: Invalid interception route: /users/(.)(.)(.)1

How

  1. Added isInterceptionRouteRewrite() helper to generate-interception-routes-rewrites.ts — identifies rewrites generated from interception routes by checking for the NEXT_URL header in the has array.

  2. In setup-dev-bundler.ts, filter out stale interception rewrites before pushing fresh ones on each HMR update.

Testing

  • Confirmed broken in 16.1.6 without fix
  • Confirmed working after fix applied to node_modules
  • This is a regression — Next.js 15.2.4 did not have this code path

Closes #91265

Changed files

  • packages/next/src/lib/generate-interception-routes-rewrites.ts (modified, +8/-0)
  • packages/next/src/server/lib/router-utils/setup-dev-bundler.ts (modified, +12/-7)
  • test/e2e/app-dir/parallel-routes-and-interception/parallel-routes-and-interception.test.ts (modified, +37/-0)

Code Example

Error: Invalid interception route: /users/(.)(.)(.)1
Must be in the format /<intercepting route>/(..|...|..)(..)/<intercepted route>

---

// Runs on EVERY HMR update — never clears!
opts.fsChecker.rewrites.beforeFiles.push(...interceptionRoutes); // BUG

---

opts.fsChecker.rewrites.beforeFiles = opts.fsChecker.rewrites.beforeFiles
    .filter(r => !_generateinterceptionroutesrewrites.isInterceptionRouteRewrite(r));
opts.fsChecker.rewrites.beforeFiles.push(...interceptionRoutes);

---

Operating System:
  Platform: win32
  Arch: x64
  Version: Windows 11 Pro
  Available memory (MB): 8039
  Available CPU cores: 8
Binaries:
  Node: 24.12.0
  npm: 11.6.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 16.1.6 // Latest available version is detected (16.1.6).
  eslint-config-next: N/A
  react: 19.2.4
  react-dom: 19.2.4
  typescript: N/A
Next.js Config:
  output: N/A
RAW_BUFFERClick to expand / collapse

Link to the code that reproduces this issue

https://github.com/aleewains/next-app

To Reproduce

  1. Create a new Next.js 16 project: npx create-next-app@latest
  2. Create the following file structure:
    • app/users/@modal/(.)[id]/page.tsx (intercepting route)
    • app/users/@modal/default.tsx (returns null)
    • app/users/[id]/page.tsx (full page)
    • app/users/layout.tsx (renders {children} and {modal} slots)
    • app/users/page.tsx
  3. Start dev server: npm run dev
  4. Navigate to http://localhost:3000/users
  5. Then click on a cardm it open a modal,
  6. Now, save any file in the project (add a space and save)
  7. Observe the error in the terminal
  8. also oberve interception-route-rewrite-manifest file in .next/server
  9. video link explaining https://drive.google.com/file/d/1PBaVuGAvnZzVYZF5IY4NC_9Oe9fJs6Ez/view

Current vs. Expected behavior

Expected: Interception routes continue working normally after HMR file saves.

Actual: The following error is thrown on every file save:

Error: Invalid interception route: /users/(.)(.)(.)1
Must be in the format /<intercepting route>/(..|...|..)(..)/<intercepted route>

The number of (.) markers increases with each save (1 save = 1 marker, 3 saves = 3 markers), proving entries accumulate. A full dev server restart is required each time to temporarily resolve it.

Root Cause (investigated): In setup-dev-bundler.js, interception routes are pushed into beforeFiles on every HMR update without clearing old entries:

// Runs on EVERY HMR update — never clears!
opts.fsChecker.rewrites.beforeFiles.push(...interceptionRoutes); // BUG

Fix — filter before pushing:

opts.fsChecker.rewrites.beforeFiles = opts.fsChecker.rewrites.beforeFiles
    .filter(r => !_generateinterceptionroutesrewrites.isInterceptionRouteRewrite(r));
opts.fsChecker.rewrites.beforeFiles.push(...interceptionRoutes);

This is a regression — Next.js 15.2.4 does not have this code at all and works correctly.

Provide environment information

Operating System:
  Platform: win32
  Arch: x64
  Version: Windows 11 Pro
  Available memory (MB): 8039
  Available CPU cores: 8
Binaries:
  Node: 24.12.0
  npm: 11.6.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 16.1.6 // Latest available version is detected (16.1.6).
  eslint-config-next: N/A
  react: 19.2.4
  react-dom: 19.2.4
  typescript: N/A
Next.js Config:
  output: N/A

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

Turbopack, Parallel & Intercepting Routes

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

next dev (local)

Additional context

  • Confirmed working in Next.js 15.2.4 (the beforeFiles.push pattern does not exist there)
  • Confirmed broken in Next.js 16.1.6
  • Manually applying the filter-before-push fix to node_modules resolves the issue completely
  • Reproducible locally on Windows 11 with Turbopack (default in Next.js 16)
  • Does NOT require deployment — purely a local dev server issue

extent analysis

Fix Plan

To resolve the issue with interception routes in Next.js 16, follow these steps:

  1. Modify the setup-dev-bundler.js file:
    • Locate the line where opts.fsChecker.rewrites.beforeFiles is being pushed with interceptionRoutes.
    • Replace that line with the following code to filter out existing interception routes before adding new ones:

opts.fsChecker.rewrites.beforeFiles = opts.fsChecker.rewrites.beforeFiles .filter(r => !_generateInterceptionRoutesRewrites.isInterceptionRouteRewrite(r)); opts.fsChecker.rewrites.beforeFiles.push(...interceptionRoutes);

2. **Apply the fix manually**:
   - Since the issue is within the `node_modules` directory, you'll need to manually apply the fix there or wait for an official update from Next.js.
   - Navigate to the `node_modules/next` directory and find the `setup-dev-bundler.js` file.
   - Apply the fix mentioned above.

### Verification
To verify that the fix worked:
- Restart your development server.
- Navigate to `http://localhost:3000/users` and interact with the modal as before.
- Save any file in the project and observe the terminal for any errors related to interception routes.
- The error should no longer appear, and the interception routes should continue working as expected after file saves.

### Extra Tips
- Keep an eye on future updates from Next.js, as this fix should be incorporated into the official package eventually.
- Consider contributing the fix back to the Next.js project if you're comfortable with their contribution process.
- For similar issues in the future, always check the differences between versions and look for changes in how certain features are handled, as regressions can often be traced back to recent updates.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING