This error occurs when React Router detects a Route component nested at a specific depth that doesn't match the actual route configuration. It typically happens when routes are improperly nested or when parent routes are missing necessary configuration.
This error message from React Router indicates a mismatch between your JSX Route component structure and the actual routing configuration that React Router can successfully match. When you see "passed a Route element at depth 3 but we could not find a matching route," it means you have Route components nested three levels deep in your JSX, but React Router's routing algorithm cannot establish a proper match for that nested structure. The issue typically arises in React Router v6 when developers nest Route components inside other components without properly configuring the parent routes or without using the Outlet component correctly. React Router v6 uses a ranked route matching system that requires all nested routes to be properly connected through their parent routes. This error is React Router's way of telling you that while your JSX structure shows a certain nesting pattern, the actual routing configuration doesn't support that pattern. The router cannot create a valid path match for the deeply nested route you've defined.
The most common cause is a missing Outlet. Check that your parent route component renders the Outlet component where child routes should appear:
// Parent component (e.g., Dashboard.tsx)
import { Outlet } from 'react-router-dom';
export function Dashboard() {
return (
<div>
<h1>Dashboard</h1>
<nav>{/* Navigation links */}</nav>
{/* This Outlet is REQUIRED for child routes to render */}
<Outlet />
</div>
);
}Without the Outlet component, React Router cannot render nested child routes, causing the depth mismatch error.
Ensure your routes are properly nested in your route configuration. In React Router v6, nested routes should be declared as children:
// App.tsx or routes configuration
import { BrowserRouter, Routes, Route } from 'react-router-dom';
function App() {
return (
<BrowserRouter>
<Routes>
<Route path="/" element={<Layout />}>
<Route index element={<Home />} />
<Route path="dashboard" element={<Dashboard />}>
{/* These child routes require Dashboard to have <Outlet /> */}
<Route path="profile" element={<Profile />} />
<Route path="settings" element={<Settings />} />
</Route>
</Route>
</Routes>
</BrowserRouter>
);
}Make sure the depth of your JSX nesting matches your intended route structure.
Don't define Route components inside other components or conditional blocks. Keep your route configuration at the top level:
// ❌ WRONG - Routes nested inside component
function Dashboard() {
return (
<div>
<Routes>
<Route path="profile" element={<Profile />} />
</Routes>
</div>
);
}
// ✅ CORRECT - Use Outlet for nested content
function Dashboard() {
return (
<div>
<Outlet />
</div>
);
}
// Define routes in top-level configuration
<Route path="dashboard" element={<Dashboard />}>
<Route path="profile" element={<Profile />} />
</Route>React Router v6 requires static route configuration for optimal performance and features.
In React Router v6, child route paths are relative to their parent by default. Don't repeat the parent path:
// ❌ WRONG - Absolute paths in nested routes
<Route path="/dashboard" element={<Dashboard />}>
<Route path="/dashboard/profile" element={<Profile />} />
</Route>
// ✅ CORRECT - Relative paths
<Route path="/dashboard" element={<Dashboard />}>
<Route path="profile" element={<Profile />} />
{/* This matches /dashboard/profile automatically */}
</Route>Using absolute paths can break the nesting relationship and cause matching errors.
If you're using splat routes (path="*"), ensure they're positioned correctly and don't interfere with nested routes:
// ❌ WRONG - Wildcard catches everything before specific routes
<Route path="/dashboard" element={<Dashboard />}>
<Route path="*" element={<NotFound />} />
<Route path="profile" element={<Profile />} />
</Route>
// ✅ CORRECT - Specific routes before wildcard
<Route path="/dashboard" element={<Dashboard />}>
<Route path="profile" element={<Profile />} />
<Route path="settings" element={<Settings />} />
<Route path="*" element={<NotFound />} />
</Route>The wildcard route should be the last child route to catch unmatched paths.
Check your package.json to ensure you're not accidentally mixing React Router v5 and v6:
npm ls react-router-domIf you see multiple versions, update to use only v6:
npm install react-router-dom@latestReact Router v6 has different APIs for nested routing compared to v5, and mixing versions causes configuration mismatches.
Understanding Route Depth Tracking: React Router v6 internally tracks the depth of Route components to optimize matching and rendering. The "depth" in the error message refers to the JSX nesting level of Route components, not the URL path depth. This distinction is important because you can have deep URL paths with shallow route nesting, or vice versa.
Static Route Configuration Benefits: React Router v6 strongly encourages static route configuration (all routes defined upfront) rather than dynamic routes scattered across components. This enables features like data loaders, route-based code splitting, and improved matching performance. The unmatched route error often indicates you're fighting against this design pattern.
Index Routes vs Path Routes: When working with nested routes, consider using index routes for the default child route instead of an empty path:
<Route path="dashboard" element={<Dashboard />}>
<Route index element={<DashboardHome />} /> {/* Matches /dashboard exactly */}
<Route path="profile" element={<Profile />} /> {/* Matches /dashboard/profile */}
</Route>This pattern is clearer and prevents ambiguity in route matching.
RouterProvider vs BrowserRouter: If you're using the newer RouterProvider API with createBrowserRouter, ensure your route configuration object is properly structured with nested children arrays. The depth error can also occur with malformed route configuration objects.
Debugging with React DevTools: Install React DevTools and inspect the component tree when this error occurs. Look for Route components that are rendered but don't have corresponding matches. This visual inspection often reveals structural issues in your route configuration.
React Hook useCallback has a missing dependency: 'variable'. Either include it or remove the dependency array react-hooks/exhaustive-deps
React Hook useCallback has a missing dependency
Cannot use private fields in class components without TS support
Cannot use private fields in class components without TS support
Cannot destructure property 'xxx' of 'undefined'
Cannot destructure property of undefined when accessing props
useNavigate() may be used only in the context of a <Router> component.
useNavigate() may be used only in the context of a Router component
Cannot find module or its corresponding type declarations
How to fix "Cannot find module or type declarations" in Vite