Inconsistent 404 Handling with Parallel Routes
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/r4sheed/nextjs-parallel-routes-404-repro
To Reproduce
-
Set up the project:
- Option A: Clone the repository:
git clone https://github.com/r4sheed/nextjs-parallel-routes-404-repro.git cd nextjs-parallel-routes-404-repro - Option B: Use CodeSandbox:
Open the project directly in CodeSandbox: https://codesandbox.io/p/github/r4sheed/nextjs-parallel-routes-404-repro/master?import=true
Ensure you have the project files as structured. The key files for reproducing the bug are:
src/app/(main)/layout.tsx(defines the main layout with the parallel route slot)src/app/(main)/@breadcrumb/default.tsxsrc/app/(main)/@breadcrumb/[...catchAll]/page.tsx(provides the content for the breadcrumb slot)src/app/(main)/not-found.tsx(custom 404 page for the(main)group)src/app/page.tsx(root page with a link to a non-existent page)src/app/(main)/main-group-page/page.tsx(a page within the group, also with a link to a non-existent page)src/app/(main)/exists/page.tsx(another page within the group)
- Option A: Clone the repository:
-
Install dependencies:
npm install -
Run the development server:
npm run dev -
Open the application:
Open http://localhost:3000 in your browser. -
Test Scenario 1 (Correct 404):
- On the home page (
/), you will see a "Go to a page that does not exist (from root)" link. - Click this link.
- Expected: You should see the "Not Found" page defined in
src/app/(main)/not-found.tsx. The browser's network tools should show a 200 status for the navigation.
- On the home page (
-
Test Scenario 2 (Incorrect 200 OK):
- Navigate back to the home page (
/). - Click the "Go to Main Group Page" link to navigate to
/main-group-page. - On the
/main-group-page, you will see a "Go to a page that does not exist (from main-group-page)" link. - Click this link.
- Expected: You should see the "Not Found" page.
- Actual: The "Not Found" page is not displayed. The browser's network tools will show an HTTP 200 status for the navigation to
/does-not-exist. The content might remain the same as/main-group-pageor appear as an empty page, but it's not the custom 404 page. - You can repeat this by navigating to
/existsfirst and then clicking the link to/does-not-existfrom there; the behavior will be the same.
- Navigate back to the home page (
Current vs. Expected behavior
In Next.js version 15.3.2, there's an issue with inconsistent 404 error handling when using parallel routes (specifically with a @breadcrumb slot and a [...catchAll]/page.tsx segment) during client-side navigation.
What Happens (The Bug):
If you navigate from a page within a route group (e.g., from /main-group-page or /exists) to a non-existent page within that same group (e.g., /does-not-exist), the application incorrectly returns an HTTP 200 status. The custom not-found.tsx page for that group is not rendered. Instead, the content of the previous page might remain visible, or an empty page might be shown. This only happens during client-side navigation; a full page refresh of the non-existent URL correctly shows the 404 page.
What You Expected to Happen:
When navigating from any page (either the root / or a page within the (main) group like /main-group-page) to a non-existent page (e.g., /does-not-exist), the application should consistently display the custom not-found.tsx page defined for the (main) route group. The browser's network tools should indicate a 404 status for the attempted navigation to the non-existent page
Provide environment information
Operating System:
Platform: linux
Arch: x64
Version: #1 SMP PREEMPT_DYNAMIC Sun Aug 6 20:05:33 UTC 2023
Available memory (MB): 2194
Available CPU cores: 1
Binaries:
Node: 20.12.1
npm: 10.5.0
Yarn: 1.22.19
pnpm: 8.15.6
Relevant Packages:
next: 15.3.2 // Latest available version is detected (15.3.2).
eslint-config-next: 15.3.2
react: 19.1.0
react-dom: 19.1.0
typescript: 5.8.3
Next.js Config:
output: N/A
Which area(s) are affected? (Select all that apply)
Parallel & Intercepting Routes
Which stage(s) are affected? (Select all that apply)
next dev (local)
Additional context
No response
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
Clone the linked reproduction, install dependencies, and run npm run dev. Compare client-side navigation from / and from /main-group-page or /exists to /does-not-exist, focusing on the listed parallel-route files and src/app/(main)/not-found.tsx. Done means every navigation renders the custom Not Found page with the expected HTTP status instead of returning 200 or stale content.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- next.js, react, typescript
- Domain
- frontend, web-dev
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100