Relax default.tsx validation for parallel routes leaf segments (#84767)

### What?

Relaxes the overly strict `default.tsx` validation for parallel routes
to only require the file when it's actually needed (non-leaf segments
with routable children).

### Why?

The initial validation for parallel routes required `default.tsx` files
for all parallel route slots to prevent a specific issue: when
navigating to child routes, missing `default.tsx` files could cause
silent 404s in slot content, creating a confusing user experience.

However, this validation was **too strict** - it required `default.tsx`
even in cases where it wasn't actually necessary:

1. **Leaf segments** (routes with no child routes) - There are no child
routes to navigate to, so the 404 issue cannot occur
2. **Route groups** - These are organizational folders and aren't
routable themselves
3. **Catch-all parameters** - The matched segments are dynamic parameter
values, not actual child route segments

This caused false positive build errors for valid parallel route
configurations that don't have the underlying navigational issue.

NAR-448

Author: wyattjoh

crates/next-core/src/app_structure.rs

@@ -896,15 +896,24 @@ impl Issue for MissingDefaultParallelRouteIssue {
     #[turbo_tasks::function]
     async fn description(&self) -> Vc<OptionStyledString> {
         Vc::cell(Some(
-            StyledString::Text(
-                format!(
-                    "The parallel route slot \"@{}\" is missing a default.js file. When using \
-                     parallel routes, each slot must have a default.js file to serve as a \
-                     fallback.\n\nCreate a default.js file at: {}/@{}/default.js",
-                    self.slot_name, self.app_page, self.slot_name
-                )
-                .into(),
-            )
+            StyledString::Stack(vec![
+                StyledString::Text(
+                    format!(
+                        "The parallel route slot \"@{}\" is missing a default.js file. When using \
+                         parallel routes, each slot must have a default.js file to serve as a \
+                         fallback.",
+                        self.slot_name
+                    )
+                    .into(),
+                ),
+                StyledString::Text(
+                    format!(
+                        "Create a default.js file at: {}/@{}/default.js",
+                        self.app_page, self.slot_name
+                    )
+                    .into(),
+                ),
+            ])
             .resolved_cell(),
         ))
     }
@@ -940,6 +949,32 @@ fn page_path_except_parallel(loader_tree: &AppPageLoaderTree) -> Option<AppPage>
     None
 }
 
+/// Checks if a directory tree has child routes (non-parallel, non-group routes).
+/// Leaf segments don't need default.js because there are no child routes
+/// that could cause the parallel slot to unmatch.
+fn has_child_routes(directory_tree: &PlainDirectoryTree) -> bool {
+    for (name, subdirectory) in &directory_tree.subdirectories {
+        // Skip parallel routes (start with '@')
+        if is_parallel_route(name) {
+            continue;
+        }
+
+        // Skip route groups, but check if they have pages inside
+        if is_group_route(name) {
+            // Recursively check if the group has child routes
+            if has_child_routes(subdirectory) {
+                return true;
+            }
+            continue;
+        }
+
+        // If we get here, it's a regular route segment (child route)
+        return true;
+    }
+
+    false
+}
+
 async fn check_duplicate(
     duplicate: &mut FxHashMap<AppPath, AppPage>,
     loader_tree: &AppPageLoaderTree,
@@ -1200,9 +1235,20 @@ async fn directory_tree_to_loader_tree_internal(
                 //   /[...catchAll]/@slot - is_inside_catchall = true (skip validation) ✓
                 //   /@slot/[...catchAll] - is_inside_catchall = false (require default) ✓
                 // The catch-all provides fallback behavior, so default.js is not required.
+                //
+                // Also skip validation if this is a leaf segment (no child routes).
+                // Leaf segments don't need default.js because there are no child routes
+                // that could cause the parallel slot to unmatch. For example:
+                //   /repo-overview/@slot/page with no child routes - is_leaf_segment = true (skip
+                // validation) ✓   /repo-overview/@slot/page with
+                // /repo-overview/child/page - is_leaf_segment = false (require default) ✓
+                // This also handles route groups correctly by filtering them out.
+                let is_leaf_segment = !has_child_routes(directory_tree);
+
                 if key != "children"
                     && subdirectory.modules.default.is_none()
                     && !is_inside_catchall
+                    && !is_leaf_segment
                 {
                     missing_default_parallel_route_issue(
                         app_dir.clone(),
@@ -1275,10 +1321,14 @@ async fn directory_tree_to_loader_tree_internal(
 
             let is_inside_catchall = app_page.is_catchall();
 
+            // Check if this is a leaf segment (no child routes).
+            let is_leaf_segment = !has_child_routes(directory_tree);
+
             // Only emit the issue if this is not the children slot and there's no default
             // component. The children slot is implicit and doesn't require a default.js
-            // file. Also skip validation if the slot is UNDER a catch-all route.
-            if default.is_none() && key != "children" && !is_inside_catchall {
+            // file. Also skip validation if the slot is UNDER a catch-all route or if
+            // this is a leaf segment (no child routes).
+            if default.is_none() && key != "children" && !is_inside_catchall && !is_leaf_segment {
                 missing_default_parallel_route_issue(
                     app_dir.clone(),
                     app_page.clone(),

packages/next/src/build/webpack/loaders/next-app-loader/index.ts

@@ -135,6 +135,7 @@ async function createTreeCodeFromPath(
     resolveDir,
     resolver,
     resolveParallelSegments,
+    hasChildRoutesForSegment,
     metadataResolver,
     pageExtensions,
     basePath,
@@ -148,6 +149,7 @@ async function createTreeCodeFromPath(
     resolveParallelSegments: (
       pathname: string
     ) => [key: string, segment: string | string[]][]
+    hasChildRoutesForSegment: (segmentPath: string) => boolean
     loaderContext: webpack.LoaderContext<AppLoaderOptions>
     pageExtensions: PageExtensions
     basePath: string
@@ -560,9 +562,23 @@ async function createTreeCodeFromPath(
             //   /@slot/[...catchAll] - isInsideCatchAll = false (require default) ✓
             // The catch-all provides fallback behavior, so default.js is not required.
             const isInsideCatchAll = segments.some(isCatchAllSegment)
-            if (!isInsideCatchAll) {
+
+            // Check if this is a leaf segment (no child routes).
+            // Leaf segments don't need default.js because there are no child routes
+            // that could cause the parallel slot to unmatch. For example:
+            //   /repo-overview/@slot/page with no child routes - isLeafSegment = true (skip validation) ✓
+            //   /repo-overview/@slot/page with /repo-overview/child/page - isLeafSegment = false (require default) ✓
+            // This also handles route groups correctly by filtering them out.
+            const isLeafSegment = !hasChildRoutesForSegment(segmentPath)
+
+            if (!isInsideCatchAll && !isLeafSegment) {
+              // Replace internal webpack alias with user-facing directory name
+              const userFacingPath = fullSegmentPath.replace(
+                APP_DIR_ALIAS,
+                'app'
+              )
               throw new MissingDefaultParallelRouteError(
-                fullSegmentPath,
+                userFacingPath,
                 adjacentParallelSegment
               )
             }
@@ -726,6 +742,44 @@ const nextAppLoader: AppLoader = async function nextAppLoader() {
     return Object.entries(matched)
   }
 
+  const hasChildRoutesForSegment = (segmentPath: string): boolean => {
+    const pathPrefix = segmentPath ? `${segmentPath}/` : ''
+
+    for (const appPath of normalizedAppPaths) {
+      if (appPath.startsWith(pathPrefix)) {
+        const rest = appPath.slice(pathPrefix.length).split('/')
+
+        // Filter out route groups to get the actual route segments
+        // Route groups (e.g., "(group)") don't contribute to the URL path
+        const routeSegments = rest.filter((segment) => !isGroupSegment(segment))
+
+        // If it's just 'page' at this level, skip (not a child route)
+        if (routeSegments.length === 1 && routeSegments[0] === 'page') {
+          continue
+        }
+
+        // If the first segment (after filtering route groups) is a parallel route, skip
+        if (routeSegments[0]?.startsWith('@')) {
+          continue
+        }
+
+        // If we have more than just 'page', then there are child routes
+        // Examples:
+        //   ['child', 'page'] -> true (has child route)
+        //   ['page'] -> false (already filtered above)
+        //   ['grandchild', 'deeper', 'page'] -> true (has nested child routes)
+        if (
+          routeSegments.length > 1 ||
+          (routeSegments.length === 1 && routeSegments[0] !== 'page')
+        ) {
+          return true
+        }
+      }
+    }
+
+    return false
+  }
+
   const resolveDir: DirResolver = (pathToResolve) => {
     return createAbsolutePath(appDir, pathToResolve)
   }
@@ -832,6 +886,7 @@ const nextAppLoader: AppLoader = async function nextAppLoader() {
     resolver,
     metadataResolver,
     resolveParallelSegments,
+    hasChildRoutesForSegment,
     loaderContext: this,
     pageExtensions,
     basePath,
@@ -889,6 +944,7 @@ const nextAppLoader: AppLoader = async function nextAppLoader() {
         resolver,
         metadataResolver,
         resolveParallelSegments,
+        hasChildRoutesForSegment,
         loaderContext: this,
         pageExtensions,
         basePath,

packages/next/src/shared/lib/errors/missing-default-parallel-route-error.ts

@@ -8,5 +8,9 @@ export class MissingDefaultParallelRouteError extends Error {
     )
 
     this.name = 'MissingDefaultParallelRouteError'
+
+    // This error is meant to interrupt the server start/build process
+    // but the stack trace isn't meaningful, as it points to internal code.
+    this.stack = undefined
   }
 }

test/e2e/app-dir/parallel-routes-leaf-segments/fixtures/build-error/README.md

@@ -0,0 +1,125 @@
+# Build Error Scenarios
+
+This fixture contains scenarios that **SHOULD throw `MissingDefaultParallelRouteError`** during build.
+
+## Why These Should Error
+
+All scenarios in this fixture have:
+1. ✅ Parallel routes (slots starting with `@`)
+2. ❌ **NO** `default.tsx` files for those parallel routes
+3. ✅ **Child routes** that make these **non-leaf segments**
+
+The presence of child routes means `default.tsx` files are required for the parallel slots.
+
+---
+
+## Scenario 1: Non-Leaf Segment with Children
+
+**Path:** `/with-children`
+
+```
+app/with-children/
+├── @header/
+│   └── page.tsx              ← Has page.tsx
+│   ❌ NO default.tsx!        ← Missing default.tsx
+├── @sidebar/
+│   └── page.tsx              ← Has page.tsx
+│   ❌ NO default.tsx!        ← Missing default.tsx
+├── layout.tsx                ← Uses @header and @sidebar
+├── page.tsx                  ← Parent page
+└── child/
+    └── page.tsx              ← ⚠️ CHILD ROUTE EXISTS!
+```
+
+**Expected Error:**
+```
+MissingDefaultParallelRouteError:
+  Missing required default.js file for parallel route at /with-children/@header
+  The parallel route slot "@header" is missing a default.js file.
+```
+
+**Why it errors:**
+- When navigating from `/with-children` to `/with-children/child`, the routing system needs to know what to render for the `@header` and `@sidebar` slots
+- Since `/with-children/child` doesn't define these parallel routes, Next.js looks for `default.tsx` files
+- No `default.tsx` files exist → ERROR!
+
+---
+
+## Scenario 2: Non-Leaf with Route Groups and Children
+
+**Path:** `/with-groups-and-children`
+
+```
+app/with-groups-and-children/(dashboard)/(overview)/
+├── @analytics/
+│   └── page.tsx              ← Has page.tsx
+│   ❌ NO default.tsx!        ← Missing default.tsx
+├── @metrics/
+│   └── page.tsx              ← Has page.tsx
+│   ❌ NO default.tsx!        ← Missing default.tsx
+├── layout.tsx                ← Uses @analytics and @metrics
+├── page.tsx                  ← Parent page
+└── nested/
+    └── page.tsx              ← ⚠️ CHILD ROUTE EXISTS!
+```
+
+**Route Groups:** `(dashboard)` and `(overview)` don't affect the URL
+
+**Expected Error:**
+```
+MissingDefaultParallelRouteError:
+  Missing required default.js file for parallel route at /with-groups-and-children/(dashboard)/(overview)/@analytics
+  The parallel route slot "@analytics" is missing a default.js file.
+```
+
+**Why it errors:**
+- Even with route groups, the segment has a child route (`/nested`)
+- The `hasChildRoutesForSegment()` helper correctly:
+  1. Filters out route groups `(dashboard)` and `(overview)`
+  2. Detects the `nested/page.tsx` child route
+  3. Identifies this as a **non-leaf segment**
+- No `default.tsx` files exist → ERROR!
+
+---
+
+## How to Fix These Errors
+
+To make these scenarios build successfully, add `default.tsx` files:
+
+### For Scenario 1:
+```tsx
+// app/with-children/@header/default.tsx
+export default function HeaderDefault() {
+  return <div>Header Fallback</div>
+}
+
+// app/with-children/@sidebar/default.tsx
+export default function SidebarDefault() {
+  return <div>Sidebar Fallback</div>
+}
+```
+
+### For Scenario 2:
+```tsx
+// app/with-groups-and-children/(dashboard)/(overview)/@analytics/default.tsx
+export default function AnalyticsDefault() {
+  return <div>Analytics Fallback</div>
+}
+
+// app/with-groups-and-children/(dashboard)/(overview)/@metrics/default.tsx
+export default function MetricsDefault() {
+  return <div>Metrics Fallback</div>
+}
+```
+
+---
+
+## Contrast with `no-build-error` Fixture
+
+The `no-build-error` fixture has similar parallel routes but:
+- ❌ **NO child routes** (leaf segments)
+- ✅ `default.tsx` files are **NOT required**
+
+This fixture (build-error) has:
+- ✅ **Child routes exist** (non-leaf segments)
+- ❌ `default.tsx` files **ARE required** but missing → **ERROR!**

test/e2e/app-dir/parallel-routes-leaf-segments/fixtures/build-error/app/layout.tsx

@@ -0,0 +1,11 @@
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}

test/e2e/app-dir/parallel-routes-leaf-segments/fixtures/build-error/app/page.tsx

@@ -0,0 +1,27 @@
+import Link from 'next/link'
+
+export default function HomePage() {
+  return (
+    <div>
+      <h1>Build Error Scenarios Test</h1>
+      <p>
+        These routes SHOULD cause MissingDefaultParallelRouteError because they
+        have parallel routes without default.tsx files AND have child routes.
+      </p>
+      <nav>
+        <ul>
+          <li>
+            <Link href="/with-children">
+              Non-Leaf Segment with Children (SHOULD ERROR)
+            </Link>
+          </li>
+          <li>
+            <Link href="/with-groups-and-children">
+              Non-Leaf with Route Groups and Children (SHOULD ERROR)
+            </Link>
+          </li>
+        </ul>
+      </nav>
+    </div>
+  )
+}

test/e2e/app-dir/parallel-routes-leaf-segments/fixtures/build-error/app/with-children/@header/page.tsx

@@ -0,0 +1,8 @@
+export default function HeaderSlot() {
+  return (
+    <div>
+      <h3>Header Slot (Parent)</h3>
+      <p>This is the @header parallel route</p>
+    </div>
+  )
+}