react-navigation/react-navigation · error

Couldn't find a navigation object. Is your component inside

Error message

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

What it means

useBuildAction (used by useLinkBuilder's buildAction) reads the NavigationContainerRefContext to get the root navigation object for constructing link actions. If the context is undefined, the hook is being called outside a NavigationContainer, so it cannot resolve navigation state and the library throws.

Source

Thrown at packages/native/src/useLinkBuilder.tsx:101

      options?.enabled,
      options?.config,
      isScreen,
      focusedRouteState,
      getPathFromStateHelper,
    ]
  );

  return buildHref;
}

/**
 * Helper to build a navigation action from a href based on the linking options.
 */
export function useBuildAction() {
  const navigation = React.use(NavigationContainerRefContext);

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

  const { options } = React.use(LinkingContext);

  const getActionFromStateHelper =
    options?.getActionFromState ?? getActionFromState;

  const buildAction = React.useCallback(
    (href: string) => {
      const rootState = navigation.getRootState();

      const state = getStateFromHref(href, options, rootState);

      if (state) {
        const action =
          getActionFromStateHelper(state, options?.config) ??

View on GitHub (pinned to ab1319d6bb)

Solutions

Move the component (or the hook call) inside the component tree under <NavigationContainer>, ideally inside a screen.
Ensure NavigationContainer wraps all components that call useLinkBuilder before any hook usage.
If the component must live outside, pass a href builder down as props from an in-tree component.
In tests/Storybook, wrap the component in a NavigationContainer (with a minimal navigator) before rendering.

Example fix

// before
function App() {
  const buildAction = useBuildAction();
  return <NavigationContainer>{/* ... */}</NavigationContainer>;
}
// after
function App() {
  return (
    <NavigationContainer>
      <LinkButton />  // hook used inside the container
    </NavigationContainer>
  );
}

Defensive patterns

Strategy: type-guard

Validate before calling

const nav = React.use(NavigationContainerRefContext);
if (nav === undefined) {
  // don't call useBuildAction-dependent logic; render a disabled link
}

Type guard

function isInsideNavigationContainer(): boolean {
  return React.use(NavigationContainerRefContext) !== undefined;
}

Try / catch

try {
  const action = buildAction(href);
} catch (e) {
  if (String(e.message).includes("Couldn't find a navigation object")) {
    // render non-navigating fallback (disabled button / external Linking.openURL)
  } else throw e;
}

Prevention

Only call useLinkBuilder/useBuildAction in components under <NavigationContainer>.
Keep link-building components inside screens, not at the app root.
Wrap Storybook/test renders in a NavigationContainer.
Lift the hook call into an in-tree component and pass results down as props.

When it happens

Trigger: Calling useLinkBuilder/useBuildAction in a component rendered outside <NavigationContainer>, e.g. in a root App component above the container, in a modal mounted at the app root, or in tests without a container wrapper.

Common situations: Custom link buttons/buttons placed outside the navigator tree; components extracted to app root for layout reasons; Storybook/tests rendering link components standalone.

Related errors

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