You navigate to a page in your app and TanStack Router throws:

Route not found

Or in some versions:

Error: Could not find match for path "/your-path"

The router can’t match the current URL to any route in your route tree.

What causes this

TanStack Router uses a route tree — a hierarchical structure where every route must be explicitly registered. Unlike file-based routers (Next.js, Remix), TanStack Router doesn’t auto-discover routes. If a route isn’t in the tree, it doesn’t exist.

Common causes:

• You created a route component but forgot to add it to the route tree
• The route path doesn’t match the URL (typo, missing leading slash, wrong parameter syntax)
• You’re using file-based routing but the file isn’t in the right directory or doesn’t follow the naming convention
• A parent route is missing, breaking the hierarchy
• You deployed a new route but the client is still running old code

Fix 1: Add the missing route to the route tree

Every route must be registered as a child of its parent. Check your route tree definition:

const routeTree = rootRoute.addChildren([
  indexRoute,
  aboutRoute,
  // ❌ If dashboardRoute is missing here, /dashboard will 404
  dashboardRoute,
]);

If you’re using the code-based approach, make sure every route is wired up. It’s easy to create a Route object and forget to add it to addChildren.

Fix 2: Check your route path definitions

Make sure the path in your route definition matches what you expect:

// ❌ Wrong — leading slash not needed in TanStack Router
const aboutRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/about',
});

// ✅ Correct
const aboutRoute = new Route({
  getParentRoute: () => rootRoute,
  path: 'about',
});

For dynamic segments, use the $ prefix:

const userRoute = new Route({
  getParentRoute: () => rootRoute,
  path: 'users/$userId',
});

Fix 3: Add a catch-all / not-found route

You should always have a fallback route to handle unmatched URLs gracefully instead of throwing an error:

const notFoundRoute = new NotFoundRoute({
  getParentRoute: () => rootRoute,
  component: () => <div>404 — Page not found</div>,
});

const router = new Router({
  routeTree,
  notFoundRoute,
});

This catches any URL that doesn’t match a defined route and renders your 404 component instead of crashing.

Fix 4: Regenerate the route tree (file-based routing)

If you’re using TanStack Router’s file-based routing with the Vite plugin, the route tree is auto-generated. Sometimes it gets out of sync:

# Delete the generated route tree and restart dev server
rm src/routeTree.gen.ts
npm run dev

Make sure your route files follow the naming convention. For example, src/routes/about.tsx creates the /about route. Nested routes use directories: src/routes/dashboard/settings.tsx creates /dashboard/settings.

Related resources

• React complete guide

How to prevent it

• Always add a NotFoundRoute to your router — it’s a safety net you’ll always need
• If using code-based routing, keep your route tree definition close to your route declarations so you don’t forget to register new routes
• If using file-based routing, let the Vite plugin handle generation and don’t manually edit routeTree.gen.ts
• Use TypeScript — TanStack Router has excellent type safety that will catch missing routes at compile time when configured properly

Related: React Interview Questions