{"record":{"id":"c96b5e6e09e3de48","repo":"react-navigation/react-navigation","slug":"got-invalid-href-href-it-must-start-with","errorCode":null,"errorMessage":"Got invalid href '${href}'. It must start with '/' or match one of the prefixes: ${options?.prefixes?.map((prefix) => `'${prefix}'`).join(', ')}.","messagePattern":"Got invalid href '(.+?)'\\. It must start with '/' or match one of the prefixes: (.+?)'`\\)\\.join\\(', '\\)\\}\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/native/src/getStateFromHref.tsx","lineNumber":43,"sourceCode":"    path = href;\n  } else if (href) {\n    if (filter && !filter(href)) {\n      throw new Error(\n        `Failed to parse href '${href}'. It doesn't match the filter specified in linking config.`\n      );\n    }\n\n    if (prefixes == null || prefixes.length === 0) {\n      throw new Error(\n        `Failed to parse href '${href}'. It doesn't start with '/' and no prefixes are defined in linking config.`\n      );\n    }\n\n    path = extractPathFromURL(prefixes, href);\n  }\n\n  if (path == null) {\n    throw new Error(\n      `Got invalid href '${href}'. It must start with '/' or match one of the prefixes: ${options?.prefixes?.map((prefix) => `'${prefix}'`).join(', ')}.`\n    );\n  }\n\n  const state = getStateFromPathHelper(path, config, previous);\n\n  return state;\n}\n","sourceCodeStart":25,"sourceCodeEnd":52,"githubUrl":"https://github.com/react-navigation/react-navigation/blob/ab1319d6bbf05eae8dc25e33cbf4dc56494e0f0c/packages/native/src/getStateFromHref.tsx#L25-L52","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconst linking = { prefixes: ['myapp://'], config: {...} };\n// after\nconst linking = { prefixes: ['myapp://', 'https://app.example.com', 'https://www.app.example.com'], config: {...} };","handlingStrategy":"try-catch","validationCode":"function extractPath(prefixes, href) {\n  for (const p of prefixes ?? []) {\n    if (href.startsWith(String(p).replace(/\\/$/, ''))) {\n      return '/' + href.slice(String(p).replace(/\\/$/, '').length).replace(/^\\/+/, '');\n    }\n  }\n  return null; // no prefix matches -> would throw\n}","typeGuard":null,"tryCatchPattern":"try {\n  const state = getStateFromHref(href, options);\n} catch (e) {\n  if (String(e.message).startsWith('Got invalid href')) {\n    // unmatched prefix: navigate to a fallback route or ignore\n  } else throw e;\n}","preventionTips":["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."],"tags":["linking","url-parsing","deep-linking","react-navigation"],"backgroundTag":"url-prefix-mismatch","analyzedSha":"ab1319d6bbf05eae8dc25e33cbf4dc56494e0f0c","analyzedAt":"2026-08-31T14:46:19.520Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}