expo/expo · error · Error

The initial route name "${initialRouteName}"${groupName ? `

Error message

The initial route name "${initialRouteName}"${groupName ? ` for group "${groupName}"` : ''} was not found in the layout at "${node.contextKey}". Available routes are: ${node.children.map(({ route }) => `"${route}"`).join(', ')}. Set `unstable_settings.initialRouteName` to the name of a route in this layout.

What it means

Thrown by getValidInitialRoute (packages/expo-router/src/Route.tsx:106) when the initialRouteName set in a layout's unstable_settings does not match any direct child route of that layout. Matching is by the child's route segment (findRouteNodeByName also accepts `${name}/index`), and the error lists every route the layout actually has so you can correct the setting.

Source

Thrown at packages/expo-router/src/Route.tsx:129

    state = route?.state;
  }

  return { routeNode, params };
}

export function getValidInitialRoute(
  node: RouteNode | null,
  initialRouteName = node?.initialRouteName,
  groupName?: string
): RouteNode | undefined {
  if (!node || !initialRouteName) {
    return undefined;
  }
  const route =
    findRouteNodeByName(node, initialRouteName) ||
    findRouteNodeByName(node, `${initialRouteName}/index`);
  if (!route) {
    throw new Error(
      `The initial route name "${initialRouteName}"${groupName ? ` for group "${groupName}"` : ''} was not found in the layout at "${node.contextKey}". ` +
        `Available routes are: ${node.children.map(({ route }) => `"${route}"`).join(', ')}. ` +
        'Set `unstable_settings.initialRouteName` to the name of a route in this layout.'
    );
  }
  return route;
}

export const getValidInitialRouteName = (
  node: RouteNode | null,
  initialRouteName = node?.initialRouteName
) => getValidInitialRoute(node, initialRouteName)?.route;

export function useContextKey(): string {
  const node = useRouteNode();
  if (node == null) {
    throw new Error('No filename found. This is likely a bug in expo-router.');
  }

View on GitHub (pinned to 7da61120be)

Solutions

1. Set initialRouteName to one of the route names printed in the error's 'Available routes are' list (exact case)
2. For a directory route, the directory name works if it contains index.tsx (matches `name/index`)
3. If the target screen lives in a nested layout, move the unstable_settings export to that deeper layout instead
4. If you renamed files, update every unstable_settings.initialRouteName that references the old name

Example fix

// before — app/(tabs)/_layout.tsx, but files are app/(tabs)/index.tsx and app/(tabs)/settings.tsx
export const unstable_settings = { initialRouteName: 'home' };
// after
export const unstable_settings = { initialRouteName: 'settings' };

// dev-time check: confirm the direct child exists for the layout's initialRouteName
import fs from 'node:fs';
import path from 'node:path';

function assertInitialRouteExists(appDir: string, layoutDir: string, name: string) {
  const dir = path.join(appDir, layoutDir);
  const candidates = [`${name}.tsx`, `${name}.ts`, path.join(name, 'index.tsx'), path.join(name, 'index.tsx')];
  const ok = candidates.some((c) => fs.existsSync(path.join(dir, c)));
  if (!ok) throw new Error(`initialRouteName "${name}" matches no direct child of app/${layoutDir}`);
}

When it happens

Trigger: Exporting export const unstable_settings = { initialRouteName: 'home' } from app/(tabs)/_layout.tsx when no app/(tabs)/home.tsx or app/(tabs)/home/index.tsx exists; renaming a route file without updating unstable_settings; pointing at a nested/grandchild route (e.g. 'details/1') instead of a direct child; using a route group name like '(auth)'.

Common situations: Adding an auth gate that should start on 'login' or 'sign-in' but the file is named differently (SignIn.tsx → route 'SignIn', case-sensitive); reorganizing folders; referencing the tab bar's screen by its title instead of its file route name.

Related errors

• Input should not be `index`
• Input should not start with `/`
• Input should not end with `/`
• Attempted to link to route when no routes are present
• No routes found

AI-assisted analysis of expo/expo@7da61120be (2026-09-09). Data as JSON: /api/errors/41f0a904a3c1bb80. Report an issue: GitHub.