react-navigation/react-navigation · error

Couldn't find a navigation builder context. Is your componen

Error message

Couldn't find a navigation builder context. Is your component inside NavigationContainer?

What it means

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.

Source

Thrown at packages/core/src/NavigationBuilderContext.tsx:95

  onOptionsChange: (options: object) => void;
  getIsStateEmitted: () => boolean;
  scheduleUpdate: (callback: () => void) => void;
  flushUpdates: () => void;
  withStackTrace: WithStackTrace;
};

/**
 * Context which holds the required helpers needed to build nested navigators.
 */
export const NavigationBuilderContext = React.createContext<
  NavigationBuilderContextValue | undefined
>(undefined);

export function useNavigationBuilderContext() {
  const value = React.use(NavigationBuilderContext);

  if (value == null) {
    throw new Error(
      "Couldn't find a navigation builder context. Is your component inside NavigationContainer?"
    );
  }

  return value;
}

View on GitHub (pinned to ab1319d6bb)

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

Example fix

// before
render(<MyNavigator />); // test throws
// after
render(
  <NavigationContainer>
    <MyNavigator />
  </NavigationContainer>
);

Defensive patterns

Strategy: try-catch

Validate before calling

import { NavigationContainer } from '@react-navigation/native';
// Ensure container is an ancestor before rendering builders
const hasContainer = /* tree check */ true;
if (!hasContainer) throw new Error('Render inside NavigationContainer');

Type guard

function isBuilderContext(v: unknown): boolean {
  return v != null && typeof v === 'object' &&
    typeof (v as any).addListener === 'function';
}

Try / catch

let ctx;
try {
  ctx = useNavigationBuilderContext();
} catch (e) {
  if (e instanceof Error && e.message.includes('navigation builder context')) {
    throw new Error('Component must be rendered inside <NavigationContainer>');
  }
  throw e;
}

Prevention

Render anything using navigation builder hooks under NavigationContainer
Wrap test/story mounts in NavigationContainer
Never render a navigator above or beside the container

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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