Dynamic Routes in Next.js 16 — Wrong [slug] Matched 404 for 40% of Product Pages

Next.js file-system routing is elegant until it is not. The problem surfaces when you have multiple dynamic segments at the same level — /products/[category]/[product] and /products/[...slug] living side by side. The router picks one, and it is rarely the one you expect.

This article breaks down how Next.js resolves dynamic route conflicts, why route groups ((dashboard)) interact poorly with dynamic segments, and how to diagnose the 'wrong route matched' bug that caused 40% of product pages to 404 in a recent production incident.

Tested on Next.js 16.0.0-canary with App Router. The resolution rules are identical in Next.js 14 and 15 — this is a design invariant, not a versioning bug.

The File-System Router Is Not Smart — It Is Deterministic

Next.js App Router resolves routes by file-system traversal. It does not evaluate which route is more specific — it picks the first hit in a deterministic priority list:

1. Static segments (exact literal paths like /products/featured)
2. Dynamic single segments ([param] like [category])
3. Catch-all segments ([...param] like [...slug])
4. Optional catch-all ([[...param]] like [[...slug]])

This priority is documented but easy to miss when adding a new route. The order within each tier is alphabetical by folder name. So app/products/[category] and app/products/[...slug] are both tier 2 dynamic segments. If the file system sorts [...slug] before [category] (it usually does because '[' sorts before brackets with content), Next.js resolves [...slug] first.

The '[id]' pattern sorts before '[...slug]' lexicographically in most platforms — but '[category]' and '[...slug]' have no guaranteed priority. The result is unpredictable behavior depending on your OS and how the file system orders bracket-prefixed directory names.

This is why the fix is never 'reorder your folders' — it is always 'add a literal prefix segment'.

Route Groups ((folder)): They Drop from URL but Not from Route Resolution

Route groups are parentheses-folders that organize layouts without affecting the URL path. app/(marketing)/about/page.tsx renders at /about. The parenthesis content is stripped from the URL.

The trap: route groups create a nesting level in the route tree but not in the URL. If you have app/(marketing)/products/[slug] and app/products/[...catchall], those two routes are siblings in URL space — but the file system places them in different branches. Next.js resolves routes by file-system path first, then maps to URL. The result is that (marketing)/products/[slug] may shadow app/products/[...catchall] or vice versa, depending on the sort order of the two directory structures.

Route groups should not be used to organize routes that share URL paths. They are for layout grouping only. If two routes need different layouts but share URL patterns, use parallel routes instead. If they need no layout relationship, put them in completely separate directory trees.

Catch-All [...slug] vs Optional Catch-All [[...slug]]: The Empty Array Edge Case

The difference between [...slug] and [[...slug]] is precisely one edge case: the root path. app/products/[...slug]/page.tsx matches /products/a and /products/a/b but NOT /products. app/products/[[...slug]]/page.tsx matches all three: /products, /products/a, and /products/a/b.

The catch-all variant passes an array: params.slug = ['a'] for /products/a. Optional catch-all passes an empty array for /products: params.slug = []. Handle this case or your root product listing page 404s.

In the production incident described earlier, the team used [...slug] instead of [[...slug]], so /products (the root listing) continued working via the [category]/[product] route. But /products/a/b (three segments) was caught by [...slug] before [category]/[product] could handle it. The fix with [[...slug]] would not have helped — the root case was fine. The issue was priority, not parameters.

Choose catch-all patterns deliberately: use [...slug] when the root path has its own handler, use [[...slug]] when the catch-all should also handle the root case.

export default async function ProductsPage({
  params
}: {
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params

  // slug is undefined for /products (if using [...slug])
  // slug is [] for /products (if using [[...slug]])
  // slug is ['category'] for /products/category
  // slug is ['category', 'product'] for /products/category/product

  if (!slug || slug.length === 0) {
    // Root listing page — show all products
    return <ProductListing />
  }

  if (slug.length === 1) {
    // Category page — /products/category
    return <CategoryPage categorySlug={slug[0]} />
  }

  if (slug.length === 2) {
    // Product page — /products/category/product
    return <ProductPage categorySlug={slug[0]} productSlug={slug[1]} />
  }

  // Deeper nesting — 404 or CMS content
  notFound()
}

Route Resolution Order: The Full Priority Table with Examples

Next.js resolves routes in this exact priority order when multiple routes match the same URL:

1. Static routes (exact match) — /products/featured
2. Single dynamic segments — /products/[category]
3. Catch-all segments — /products/[...slug]
4. Optional catch-all — /products/[[...slug]]
5. Root handler — /products/page.tsx

Within each tier, lexical order of the folder name determines priority. 'a' sorts before 'b', '[a]' sorts before '[b]'. But here is the problem: at the file system level, '[...slug]' and '[category]' are both dynamic — they belong to the same tier. The tier list above is misleading because it groups all dynamic patterns together.

This means [category] and [...slug] compete at the same priority level. The winner is determined by which folder name sorts first in your specific file system — ext4 on Linux sorts differently than APFS on macOS in some edge cases.

Never rely on sort order. Always test the production build output with 'next build --debug' and verify route resolution for every dynamic pattern.

# View all routes as Next.js resolves them
npx next build --debug 2>&1 | grep -E "Route|✓"

# List all dynamic route patterns in your app
find app -type d | grep -E '\[.*\]' | sort

# Check for overlapping patterns in CI
node -e "
const fs = require('fs');
const path = require('path');

function findDynamicDirs(dir, prefix = '') {
  const results = [];
  const entries = fs.readdirSync(dir, { withFileTypes: true });
  for (const entry of entries) {
    if (entry.isDirectory()) {
      const fullPath = path.join(dir, entry.name);
      if (entry.name.startsWith('[')) {
        results.push(path.join(prefix, entry.name));
      }
      results.push(...findDynamicDirs(fullPath, path.join(prefix, entry.name)));
    }
  }
  return results;
}

const dynamics = findDynamicDirs('app');
const patterns = dynamics.map(d => d.replace(/\\[.+?\\]/g, ':param'));
const unique = new Set(patterns);
if (unique.size !== patterns.length) {
  console.log('WARNING: Overlapping dynamic route patterns detected');
  process.exit(1);
}
"

Parallel Routes and Intercepting Routes: The @slot Shadow War

Parallel routes (@slot) and intercepting routes ((.)pattern) introduce modal-style navigation patterns but also introduce a unique class of route conflicts. An @slot renders a separate route tree alongside the main page — it does not replace the main route. But the slot's default.js file can shadow the slot's page.tsx in ways that are hard to debug.

When a parallel route slot has no matching page for the current URL, Next.js falls back to default.js. If default.js exists at the parent level (outside the slot directory), it is used as a fallback. But if the slot directory has no page.tsx and no default.js, the slot renders nothing — which is often interpreted as a bug.

The intercepting route pattern (.) matches a sibling route level. (.)products at app/feed/(.)products/page.tsx intercepts /products when navigated from /feed. The problem: if /products is also a catch-all like /[...slug], the intercepting route tries to match the same path. The priority between intercepting routes and regular routes depends on the navigation source — client-side navigation follows intercepting patterns, direct URL access skips them.

This dual behavior (intercept on client, skip on direct) means your page renders differently depending on navigation source. Test both paths.

// app/@modal/default.tsx
// This renders when no modal page matches the current URL
// Without this file, the @modal slot renders nothing — causing layout gaps

export default function ModalDefault() {
  return null // Slot contributes nothing to the layout
}

// app/@modal/(.)products/[id]/page.tsx
// Intercepts /products/:id when navigated from the parent route

export default async function InterceptedProductModal({
  params
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const product = await fetch(`https://api.example.com/products/${id}`, {
    cache: 'force-cache'
  }).then(r => r.json())

  return (
    <div className="modal-overlay">
      <div className="modal-content">
        <h2>{product.name}</h2>
        <p>{product.description}</p>
        <Link href="/products">Close</Link>
      </div>
    </div>
  )
}

// Note: Direct navigation to /products/:id skips the intercept
// and renders the full product page at app/products/[id]/page.tsx
// This is intentional — intercept only applies on client navigation

Grouping Without Groups: Using Parallel Layouts for Multi-Level Navigation

When route groups ((folder)) feel like a hack for sharing layouts across non-adjacent routes, parallel routes offer a cleaner alternative. Instead of forcing every page under one layout, use parallel routes to compose multiple layout sections that each navigate independently.

Pattern: app/@sidebar renders a navigation sidebar. app/@main renders the content area. Both are parallel route slots fed into the same layout. The sidebar slot can navigate independently (showing different sections) while the main slot shows the primary content.

This works because each @slot renders its own matched page from the URL — the sidebar slot matches /@sidebar/... while the main slot matches /@main/... or the default route. The layout orchestrates both.

The cost: more files, more default.js files, and more cognitive overhead for new team members. Parallel routes solve layout problems but add complexity. Do not use them unless you genuinely need independent slot navigation.

// app/layout.tsx — orchestrate parallel slots

export default function RootLayout({
  children,
  sidebar,
  modal
}: {
  children: React.ReactNode
  sidebar: React.ReactNode
  modal: React.ReactNode
}) {
  return (
    <div className="app-layout">
      <aside className="sidebar">
        {sidebar}
      </aside>
      <main className="content">
        {children}
      </main>
      {modal}
    </div>
  )
}

// app/@sidebar/default.tsx
export default function SidebarDefault() {
  return <DefaultNavigation />
}

// app/@modal/default.tsx
export default function ModalDefault() {
  return null
}

// app/@sidebar/users/page.tsx — sidebar matches /users
// app/(main)/users/page.tsx — main content matches /users

Use the Build Output to Debug Routes — Not the Browser

The browser devtools show the rendered page, not the route that produced it. Use 'next build' output to verify which page.tsx matches each URL pattern. The build output lists every route and the file that handles it.

Run 'npx next build --debug' and pipe through grep for route output. The build prints something like: - /products → app/products/page.tsx (static) - /products/[category] → app/products/[category]/page.tsx (dynamic) - /products/[...slug] → app/products/[...slug]/page.tsx (catch-all)

If you see a route mapped to the wrong file, you have a conflict. The build does not warn about overlapping routes — it silently picks one. Only manual inspection reveals the conflict.

Add a CI step that compares expected route patterns against build output. Any discrepancy between your expectations and the resolved routes should fail the build.

#!/bin/bash
# CI route conflict detection
# Run after "npx next build" to catch overlapping dynamic routes

# Extract all routes from build output
ROUTES=$(npx next build --debug 2>&1 | grep -E '^[─├└]' | sed 's/.*\///' | sed 's/ .*//')

# Extract all route patterns from file system
PATTERNS=$(find app -name 'page.tsx' -exec dirname {} \; | sed 's|app/||' | sort)

# Check for multiple files that could match the same URL
# This is a simplified check — real implementation needs URL pattern collision detection

echo "Checking for overlapping dynamic routes..."

# Find dynamic segments at same depth
find app -type d -name '\[*.\]' | sed 's|app/||' | while read -r dir; do
  base=$(dirname "$dir")
  name=$(basename "$dir")
  count=$(find "app/$base" -type d -name '\[*.\]' | wc -l)
  if [ "$count" -gt 1 ]; then
    echo "WARNING: Multiple dynamic segments in $base/"
    find "app/$base" -type d -name '\[*.\]'
  fi
done

echo "Route check complete. Inspect warnings manually."