Expected a route.id in react-router processRoutes() function

Error message

Expected a route.id in react-router processRoutes() function

What it means

`createRoutesStub()` converts your stub route objects into data routes and then walks them with `processRoutes()`, which requires every route to have a truthy `id`. The converter auto-generates tree-path ids, but an explicit `id: ""` (empty string) survives conversion and is falsy, so the stub throws this invariant. It is a test-utility error: it only fires inside `createRoutesStub`/`createRoutesStub`-powered unit tests.

Source

Thrown at packages/react-router/lib/dom/ssr/routes-test-stub.tsx:189

    return (
      <FrameworkContext.Provider value={frameworkContextRef.current}>
        <RouterProvider router={routerRef.current} />
      </FrameworkContext.Provider>
    );
  };
}

function processRoutes(
  routes: StubRouteObject[],
  context: RouterContextProvider,
  manifest: AssetsManifest,
  routeModules: RouteModules,
  parentId?: string,
): DataRouteObject[] {
  return routes.map((route) => {
    if (!route.id) {
      throw new Error(
        "Expected a route.id in react-router processRoutes() function",
      );
    }

    let newRoute: DataRouteObject = {
      id: route.id,
      path: route.path,
      index: route.index,
      Component: route.Component
        ? withComponentProps(route.Component)
        : undefined,
      HydrateFallback: route.HydrateFallback
        ? withHydrateFallbackProps(route.HydrateFallback)
        : undefined,
      ErrorBoundary: route.ErrorBoundary
        ? withErrorBoundaryProps(route.ErrorBoundary)
        : undefined,
      action: route.action

View on GitHub (pinned to 6beaca3952)

Solutions

Remove the empty `id` field so the stub auto-assigns one, or set a unique non-empty id like `id: "0-1-2"` or `id: "layout"`.
Audit test fixtures for `id: ""` produced by spreads or defaults.
If building stub routes from app routes, filter/normalize ids before calling `createRoutesStub`.

Example fix

// before
createRoutesStub([
  { id: "", path: "/", Component: Home, loader },
]);

// after
createRoutesStub([
  { path: "/", Component: Home, loader },
]);

Defensive patterns

Strategy: validation

Validate before calling

const hasValidIds = (routes: StubRouteObject[]): boolean =>
  routes.every(
    (r) =>
      r.id !== "" &&
      (!r.children || hasValidIds(r.children)),
  );
if (!hasValidIds(stubRoutes)) throw new Error("stub routes have empty ids");
const Stub = createRoutesStub(stubRoutes);

Prevention

Omit the id field in stub routes unless you need a stable id; the stub auto-generates tree-path ids.
Never default ids to empty strings when mapping app routes to stub routes.
Keep test fixtures type-checked against StubRouteObject.

When it happens

Trigger: Passing a route object with `id: ""` to `createRoutesStub(routes)`; spreading a route config where an optional `id` field is present but an empty string; reusing real-app route objects whose ids were conditionally assigned and ended up as empty strings.

Common situations: Unit-testing components with `createRoutesStub` while mapping real route configs into stubs; generating ids programmatically (`id: route.id ?? ""`) instead of omitting the key; copy-pasting a route object and clearing the id during test setup.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of remix-run/react-router@6beaca3952 (2026-08-18). Data as JSON: /api/errors/647a5880611d683f. Report an issue: GitHub.