react-navigation/react-navigation · error · Error

Couldn't find a route at index ${state.index}.

Error message

Couldn't find a route at index ${state.index}.

What it means

MaterialTopTabBar reads state.routes[state.index] to determine the focused route for the tab bar. A null/undefined focused route means the navigator state is inconsistent (index points past the routes array), so the bar throws early rather than rendering with undefined options.

Source

Thrown at packages/material-top-tabs/src/views/MaterialTopTabBar.tsx:49

const renderLabelDefault = (props: MaterialLabelProps) => (
  <MaterialLabel {...props} />
);

export function MaterialTopTabBar({
  state,
  navigation,
  descriptors,
  ...rest
}: MaterialTopTabBarProps) {
  const { colors, dark } = useTheme();
  const { direction } = useLocale();
  const { buildHref } = useLinkBuilder();

  const focusedRoute = state.routes[state.index];

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

  const focusedOptions = descriptors[focusedRoute.key]?.options ?? {};
  const tabBarVariant = focusedOptions.tabBarVariant ?? 'primary';

  const activeColor: ColorValue =
    focusedOptions.tabBarActiveTintColor ??
    (tabBarVariant === 'primary' ? colors.primary : colors.text);

  const inactiveColor: ColorValue =
    focusedOptions.tabBarInactiveTintColor ??
    Color(colors.text)?.alpha(0.68).string() ??
    (dark ? 'rgba(255, 255, 255, 0.68)' : 'rgba(0, 0, 0, 0.68)');

  const pressColor: ColorValue =
    focusedOptions.tabBarPressColor ??
    Color(tabBarVariant === 'primary' ? colors.primary : colors.text)
      ?.alpha(0.12)

View on GitHub (pinned to ab1319d6bb)

Solutions

1. Clear persisted navigation state (remove the stored key from storage) so the navigator rebuilds a valid state.
2. Stop dispatching hand-crafted state updates; use supported actions (CommonActions.navigate, jumpTo) instead.
3. Upgrade @react-navigation/* packages to matching latest versions, since mismatched core versions can corrupt state.
4. Validate restored state shape before passing to initialState (ensure routes.length > index).

Example fix

// before
<NavigationContainer initialState={JSON.parse(stored)} />
// after
const initial = JSON.parse(stored);
const safe = initial && initial.routes && initial.index < initial.routes.length ? initial : undefined;
<NavigationContainer initialState={safe} />

function isValidTabState(state) {
  return Boolean(state && Array.isArray(state.routes) && typeof state.index === 'number' && state.index >= 0 && state.index < state.routes.length);
}
// before passing to NavigationContainer/initialState:
const initialState = isValidTabState(parsed) ? parsed : undefined;

function hasValidFocusedRoute(state) {
  return state != null && Array.isArray(state.routes) && Number.isInteger(state.index) && state.routes[state.index] != null;
}

try {
  renderTabBar(state);
} catch (e) {
  if (e instanceof Error && e.message.includes("Couldn't find a route at index")) {
    resetNavigationState(); // navigation.reset to a known-good route
  } else throw e;
}

When it happens

Trigger: Rendering MaterialTopTabBar with a navigation state whose index is out of bounds — typically from custom state manipulation (navigation.dispatch with a hand-built state), a third-party state-persistence/rehydration bug, or passing a stale state to a controlled navigator.

Common situations: Persisting navigation state to AsyncStorage and restoring a corrupted/stale serialized state; deep-link handling dispatching actions that desync index; custom tab bar integrations feeding the wrong state object.

Related errors

• Couldn't find a route at index ${state.index}.
• Couldn't find a descriptor for route '${focusedRoute.key}'.
• Couldn't find a route at index ${index}.
• No descriptor found for route "${route.name}" (${route.key})
• Couldn't find values for tab animation. Are you inside a scr

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