{"record":{"id":"f4c29d53a333b1e3","repo":"react-navigation/react-navigation","slug":"couldn-t-find-a-navigation-builder-context-is-you","errorCode":null,"errorMessage":"Couldn't find a navigation builder context. Is your component inside NavigationContainer?","messagePattern":"Couldn't find a navigation builder context\\. Is your component inside NavigationContainer\\?","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/NavigationBuilderContext.tsx","lineNumber":95,"sourceCode":"  onOptionsChange: (options: object) => void;\n  getIsStateEmitted: () => boolean;\n  scheduleUpdate: (callback: () => void) => void;\n  flushUpdates: () => void;\n  withStackTrace: WithStackTrace;\n};\n\n/**\n * Context which holds the required helpers needed to build nested navigators.\n */\nexport const NavigationBuilderContext = React.createContext<\n  NavigationBuilderContextValue | undefined\n>(undefined);\n\nexport function useNavigationBuilderContext() {\n  const value = React.use(NavigationBuilderContext);\n\n  if (value == null) {\n    throw new Error(\n      \"Couldn't find a navigation builder context. Is your component inside NavigationContainer?\"\n    );\n  }\n\n  return value;\n}\n","sourceCodeStart":77,"sourceCodeEnd":102,"githubUrl":"https://github.com/react-navigation/react-navigation/blob/ab1319d6bbf05eae8dc25e33cbf4dc56494e0f0c/packages/core/src/NavigationBuilderContext.tsx#L77-L102","documentation":"useNavigationBuilderContext reads NavigationBuilderContext; if the context value is null the hook throws. This context is only provided by NavigationContainer (and parent navigators), so the hook was called outside that tree. It guards internal builder APIs (onAction, addListener, scheduleUpdate, etc.) that are meaningless without a container.","triggerScenarios":"Calling useNavigationBuilderContext (directly or via useNavigationBuilder-dependent code / custom navigator builders) in a component not rendered under NavigationContainer; testing a custom navigator without a container wrapper.","commonSituations":"Unit tests rendering a custom navigator without NavigationContainer; a helper component using navigation builder hooks rendered in a storybook story or outside the app's navigation root; refactoring that moved a navigator above the container in the tree.","solutions":["Wrap the component tree in <NavigationContainer> before rendering anything that uses navigation builder hooks","In tests, mount a minimal <NavigationContainer><Stack.Navigator/></NavigationContainer> harness around the unit","Ensure custom navigators are rendered inside the container, not beside it"],"exampleFix":"// before\nrender(<MyNavigator />); // test throws\n// after\nrender(\n  <NavigationContainer>\n    <MyNavigator />\n  </NavigationContainer>\n);","handlingStrategy":"try-catch","validationCode":"import { NavigationContainer } from '@react-navigation/native';\n// Ensure container is an ancestor before rendering builders\nconst hasContainer = /* tree check */ true;\nif (!hasContainer) throw new Error('Render inside NavigationContainer');","typeGuard":"function isBuilderContext(v: unknown): boolean {\n  return v != null && typeof v === 'object' &&\n    typeof (v as any).addListener === 'function';\n}","tryCatchPattern":"let ctx;\ntry {\n  ctx = useNavigationBuilderContext();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('navigation builder context')) {\n    throw new Error('Component must be rendered inside <NavigationContainer>');\n  }\n  throw e;\n}","preventionTips":["Render anything using navigation builder hooks under NavigationContainer","Wrap test/story mounts in NavigationContainer","Never render a navigator above or beside the container"],"tags":["react-navigation","react-context","missing-provider"],"backgroundTag":"missing-provider-context","analyzedSha":"ab1319d6bbf05eae8dc25e33cbf4dc56494e0f0c","analyzedAt":"2026-08-31T14:46:19.520Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}