{"record":{"id":"41f0a904a3c1bb80","repo":"expo/expo","slug":"the-initial-route-name-initialroutename-grou","errorCode":null,"errorMessage":"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.","messagePattern":"The initial route name \"(.+?)\"(.+?)\"` : ''\\} was not found in the layout at \"(.+?)\"\\. Available routes are: (.+?)\\) => `\"(.+?)\"`\\)\\.join\\(', '\\)\\}\\. Set `unstable_settings\\.initialRouteName` to the name of a route in this layout\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/expo-router/src/Route.tsx","lineNumber":129,"sourceCode":"    state = route?.state;\n  }\n\n  return { routeNode, params };\n}\n\nexport function getValidInitialRoute(\n  node: RouteNode | null,\n  initialRouteName = node?.initialRouteName,\n  groupName?: string\n): RouteNode | undefined {\n  if (!node || !initialRouteName) {\n    return undefined;\n  }\n  const route =\n    findRouteNodeByName(node, initialRouteName) ||\n    findRouteNodeByName(node, `${initialRouteName}/index`);\n  if (!route) {\n    throw new Error(\n      `The initial route name \"${initialRouteName}\"${groupName ? ` for group \"${groupName}\"` : ''} was not found in the layout at \"${node.contextKey}\". ` +\n        `Available routes are: ${node.children.map(({ route }) => `\"${route}\"`).join(', ')}. ` +\n        'Set `unstable_settings.initialRouteName` to the name of a route in this layout.'\n    );\n  }\n  return route;\n}\n\nexport const getValidInitialRouteName = (\n  node: RouteNode | null,\n  initialRouteName = node?.initialRouteName\n) => getValidInitialRoute(node, initialRouteName)?.route;\n\nexport function useContextKey(): string {\n  const node = useRouteNode();\n  if (node == null) {\n    throw new Error('No filename found. This is likely a bug in expo-router.');\n  }","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/expo/expo/blob/7da61120be99bcd9cc2e5dbdba6d803c21b5c68b/packages/expo-router/src/Route.tsx#L111-L147","documentation":"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.","triggerScenarios":"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)'.","commonSituations":"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.","solutions":["Set initialRouteName to one of the route names printed in the error's 'Available routes are' list (exact case)","For a directory route, the directory name works if it contains index.tsx (matches `name/index`)","If the target screen lives in a nested layout, move the unstable_settings export to that deeper layout instead","If you renamed files, update every unstable_settings.initialRouteName that references the old name"],"exampleFix":"// before — app/(tabs)/_layout.tsx, but files are app/(tabs)/index.tsx and app/(tabs)/settings.tsx\nexport const unstable_settings = { initialRouteName: 'home' };\n// after\nexport const unstable_settings = { initialRouteName: 'settings' };","handlingStrategy":"validation","validationCode":"// dev-time check: confirm the direct child exists for the layout's initialRouteName\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nfunction assertInitialRouteExists(appDir: string, layoutDir: string, name: string) {\n  const dir = path.join(appDir, layoutDir);\n  const candidates = [`${name}.tsx`, `${name}.ts`, path.join(name, 'index.tsx'), path.join(name, 'index.tsx')];\n  const ok = candidates.some((c) => fs.existsSync(path.join(dir, c)));\n  if (!ok) throw new Error(`initialRouteName \"${name}\" matches no direct child of app/${layoutDir}`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use exact file names (case-sensitive) when setting unstable_settings.initialRouteName","Prefer expo-router's typed routes so route names are checked by TypeScript","When renaming route files, grep for unstable_settings across all _layout files"],"tags":["expo-router","initialroutename","unstable-settings","layout","routing"],"backgroundTag":"route-not-found","analyzedSha":"7da61120be99bcd9cc2e5dbdba6d803c21b5c68b","analyzedAt":"2026-09-09T16:01:44.845Z","contentChangedAt":"2026-09-09T16:01:44.845Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}