What causes "Couldn't find a route at index ${i - 1}." in react-navigation/react-navigation?

Fix the state index to be within [0, routes.length - 1] before the router builds history.

react-navigation/react-navigation · error

Couldn't find a route at index ${i - 1}.

Error message

Couldn't find a route at index ${i - 1}.

What it means

With backBehavior 'order', SwitchRouter walks backwards from the current index to build history entries for every preceding route (`routes[i - 1]`) and throws if any slot is missing. A hole in the routes array (or an index past the end) breaks history construction.

Source

Thrown at packages/routers/src/SwitchRouter.tsx:98

  }

  const history: RouteHistory[] = [
    {
      type: TYPE_ROUTE,
      key: route.key,
      params: backBehavior === 'fullHistory' ? route.params : undefined,
    },
  ];

  let initialRouteIndex;

  switch (backBehavior) {
    case 'order':
      for (let i = index; i > 0; i--) {
        const route = routes[i - 1];

        if (route == null) {
          throw new Error(`Couldn't find a route at index ${i - 1}.`);
        }

        history.unshift({
          type: TYPE_ROUTE,
          key: route.key,
        });
      }

      break;

    case 'firstRoute':
      if (index !== 0) {
        const route = routes[0];

        if (route == null) {
          throw new Error("Couldn't find a route at index 0.");
        }

View on GitHub (pinned to ab1319d6bb)

Solutions

Fix the state index to be within [0, routes.length - 1] before the router builds history.
Regenerate state via getRehydratedState or navigation.reset with the current screen set.
Clear persisted navigation state when the screen list changes between app versions.
Avoid mutating state.routes directly; use router APIs that keep index consistent.

Example fix

// before
const state = persisted; // index 4, but only 3 tabs now
// after
const state = persisted.index < persisted.routes.length
  ? persisted
  : undefined; // rebuild fresh state

Defensive patterns

Strategy: validation

Validate before calling

if (!(state.index >= 0 && state.index < state.routes.length)) {
  state = undefined; // discard corrupt state, rebuild fresh
}

Type guard

function isDenseRouteState(s) {
  return !!s && Array.isArray(s.routes) && s.routes.every(r => r != null) &&
    s.index >= 0 && s.index < s.routes.length;
}

Try / catch

try {
  return router.getInitialState({ routeNames, routeParamList });
} catch (e) {
  if (String(e.message).includes("Couldn't find a route at index")) {
    return router.getInitialState({ routeNames: defaultRouteNames, routeParamList: {} });
  }
  throw e;
}

Prevention

Never splice or sparse-fill state.routes manually.
Regenerate state via getRehydratedState/getInitialState after screen changes.
Bump a storage schema key when screen sets change so old state is dropped.
Validate every state index against routes bounds before use.

When it happens

Trigger: backBehavior="order" on a Tab/Drawer navigator combined with a state whose index is greater than the number of routes, or routes array containing sparse entries from manual state manipulation.

Common situations: Removing screens (feature-flagged tabs) while persisted state still references higher indexes; manually splicing state.routes for experiments; custom routers built on SwitchRouter passing bad indexes.

Related errors

AI-assisted analysis of react-navigation/react-navigation@ab1319d6bb (2026-08-31). Data as JSON: /api/errors/18932fe67928076f. Report an issue: GitHub.