react-navigation/react-navigation · error

Got invalid href '${href}'. It must start with '/' or match

Error message

Got invalid href '${href}'. It must start with '/' or match one of the prefixes: ${options?.prefixes?.map((prefix) => `'${prefix}'`).join(', ')}.

What it means

After filtering and prefix stripping, getStateFromHref must yield a non-null path. When extractPathFromURL returns null (the href matches none of the configured prefixes) or the input is otherwise unparseable, the library throws because it cannot derive navigation state. Note the message reads prefixes from options?.prefixes, which can show 'undefined' when none are set.

Source

Thrown at packages/native/src/getStateFromHref.tsx:43

    path = href;
  } else if (href) {
    if (filter && !filter(href)) {
      throw new Error(
        `Failed to parse href '${href}'. It doesn't match the filter specified in linking config.`
      );
    }

    if (prefixes == null || prefixes.length === 0) {
      throw new Error(
        `Failed to parse href '${href}'. It doesn't start with '/' and no prefixes are defined in linking config.`
      );
    }

    path = extractPathFromURL(prefixes, href);
  }

  if (path == null) {
    throw new Error(
      `Got invalid href '${href}'. It must start with '/' or match one of the prefixes: ${options?.prefixes?.map((prefix) => `'${prefix}'`).join(', ')}.`
    );
  }

  const state = getStateFromPathHelper(path, config, previous);

  return state;
}

View on GitHub (pinned to ab1319d6bb)

Solutions

Add the missing prefix (scheme and/or domain) to linking config prefixes so the URL matches.
Normalize the incoming URL to a path ('/foo') before calling, bypassing prefix matching.
Add multiple prefix variants: with and without 'www.', all environments (staging/prod).
Filter incoming URLs upstream and skip ones not belonging to your app.

Example fix

// before
const linking = { prefixes: ['myapp://'], config: {...} };
// after
const linking = { prefixes: ['myapp://', 'https://app.example.com', 'https://www.app.example.com'], config: {...} };

Defensive patterns

Strategy: try-catch

Validate before calling

function extractPath(prefixes, href) {
  for (const p of prefixes ?? []) {
    if (href.startsWith(String(p).replace(/\/$/, ''))) {
      return '/' + href.slice(String(p).replace(/\/$/, '').length).replace(/^\/+/, '');
    }
  }
  return null; // no prefix matches -> would throw
}

Try / catch

try {
  const state = getStateFromHref(href, options);
} catch (e) {
  if (String(e.message).startsWith('Got invalid href')) {
    // unmatched prefix: navigate to a fallback route or ignore
  } else throw e;
}

Prevention

Register all domains/schemes (www/apex, staging/prod) in prefixes.
Pre-normalize external URLs to paths before parsing.
Log unmatched hrefs and add their prefixes to config.
Don't blindly parse every incoming link; verify ownership first.

When it happens

Trigger: extractPathFromURL(prefixes, href) returns null because the URL's scheme/host matches no prefix; path is null and the final guard at line ~43 fires.

Common situations: App receiving links for domains not registered in prefixes (marketing domains, region-specific domains, www vs apex); scheme typos (myapp vs myapp://); third-party share URLs; handling all incoming links in one handler instead of filtering.

Related errors

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