react-navigation/react-navigation · error

Couldn't find a screen to navigate to. Make sure to provide

Error message

Couldn't find a screen to navigate to. Make sure to provide a screen name.

What it means

When building the action for a link href, the resolved state has no screen and no action could be derived, so useLinkProps throws because there is nothing to navigate to. This happens when the href parses to an empty state or the linking config maps the path to no screen.

Source

Thrown at packages/native/src/useLinkProps.tsx:348

          e.currentTarget && 'target' in e.currentTarget
            ? [undefined, null, '', '_self'].includes(e.currentTarget.target)
            : true;

        // let the browser handle the interaction
        if (hasModifierKey || !isLeftClick || !isSelfTarget) {
          return;
        }
      }

      e?.preventDefault();

      let cloned: NavigationAction;

      if (action != null) {
        cloned = clone(action);
      } else {
        if (screen == null) {
          throw new Error(
            "Couldn't find a screen to navigate to. Make sure to provide a screen name."
          );
        }

        cloned = clone(
          CommonActions.navigate(
            screen,
            // @ts-expect-error This is already type-checked by the prop types
            params
          )
        );

        if (parent != null) {
          cloned = {
            ...cloned,
            target: navigation.getState()?.key,
          };
        }

View on GitHub (pinned to ab1319d6bb)

Solutions

1. Provide a non-empty href with a valid screen path, e.g. href="/home".
2. Ensure the linking config maps the path to a concrete screen name.
3. Validate href construction so template params never yield an empty path.
4. Fall back to a default route when href is empty.

Example fix

// before
const href = `/items/${id}`; // id undefined -> '/items/undefined' or ''
// after
const href = id ? `/items/${id}` : '/items';

if (!to || !to.startsWith('/')) {
  throw new Error(`Invalid link target: '${to}'`);
}

function isValidHref(to: unknown): to is string {
  return typeof to === 'string' && to.length > 1 && to.startsWith('/');
}

try {
  const { onPress, href } = useLinkProps({ to });
} catch (e) {
  if (e instanceof Error && e.message.includes('screen to navigate')) {
    navigateFallback('/home');
  } else { throw e; }
}

When it happens

Trigger: Calling useLinkProps/Link with an href that resolves (via getStateFromPath) to a state lacking a screen name and without a pre-built action — e.g. href='' or href='/' when no initial route is configured.

Common situations: Empty or root-only href strings passed to Link; linking config where getStateFromPath returns partial/empty state for the path; dynamically built hrefs that end up empty due to undefined route params.

Related errors

• Failed to parse href '${href}' to a navigation state.
• Expected the configuration to be an object, but got ${JSON.s
• Found invalid properties in the configuration: ${validationE
• Found invalid path '${path}'. The 'path' in the top-level co
• Couldn't find a LinkingContext context.

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