{"record":{"id":"d821354455e91f15","repo":"vercel/next.js","slug":"cannot-prefetch-href-because-it-cannot-be-con","errorCode":null,"errorMessage":"Cannot prefetch '${href}' because it cannot be converted to a URL.","messagePattern":"Cannot prefetch '(.+?)' because it cannot be converted to a URL\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/next/src/client/components/app-router-utils.ts","lineNumber":27,"sourceCode":" * Given a link href, constructs the URL that should be prefetched. Returns null\n * in cases where prefetching should be disabled, like external URLs, or\n * during development.\n * @param href The href passed to <Link>, router.prefetch(), or similar\n * @returns A URL object to prefetch, or null if prefetching should be disabled\n */\nexport function createPrefetchURL(href: string): URL | null {\n  // Don't prefetch for bots as they don't navigate.\n  if (isBot(window.navigator.userAgent)) {\n    return null\n  }\n\n  let url: URL\n  try {\n    url = new URL(addBasePath(href), window.location.href)\n  } catch (_) {\n    // TODO: Does this need to throw or can we just console.error instead? Does\n    // anyone rely on this throwing? (Seems unlikely.)\n    throw new Error(\n      `Cannot prefetch '${href}' because it cannot be converted to a URL.`\n    )\n  }\n\n  // Don't prefetch during development (improves compilation performance)\n  if (process.env.NODE_ENV === 'development') {\n    return null\n  }\n\n  // External urls can't be prefetched in the same way.\n  if (isExternalURL(url)) {\n    return null\n  }\n\n  return url\n}\n","sourceCodeStart":9,"sourceCodeEnd":44,"githubUrl":"https://github.com/vercel/next.js/blob/0ae8c72462952df163f1b1e0726641bc5b40dc93/packages/next/src/client/components/app-router-utils.ts#L9-L44","documentation":"`createPrefetchURL` throws when the href cannot be parsed into a valid URL via `new URL(addBasePath(href), window.location.href)`. This runs during prefetch attempts (including automatic prefetch from `<Link>` with prefetch enabled). Malformed hrefs, invalid URL characters, or non-string values cause the URL constructor to throw, which is caught and re-thrown with this message.","triggerScenarios":"Passing an invalid href to `<Link>`, `router.prefetch()`, or any code path that triggers prefetching where the href fails URL constructor parsing — unencoded special characters, spaces, or a completely malformed string.","commonSituations":"Dynamic href with spaces or special characters not URL-encoded; href that is undefined/null/empty coerced to a string; relative paths with invalid syntax; query params with unencoded characters breaking the URL parser.","solutions":["Validate the href with `new URL(addBasePath(href), location.href)` in a try/catch before passing to Link or prefetch.","URL-encode query parameter values with `encodeURIComponent`.","Ensure the href is a well-formed absolute URL or root-relative path.","Add a type guard to filter out invalid hrefs from dynamic data."],"exampleFix":"// before — throws if href has invalid characters\n<Link href={`/search?q=${userInput}`}>Search</Link>\n\n// after — encode the dynamic segment\n<Link href={`/search?q=${encodeURIComponent(userInput)}`}>Search</Link>\n// or validate before use:\nfunction isValidHref(h: string) {\n  try { new URL(h, window.location.href); return true } catch { return false }\n}","handlingStrategy":"validation","validationCode":"import { addBasePath } from 'next/dist/client/add-base-path'\nfunction isValidPrefetchHref(href: string): boolean {\n  try {\n    new URL(addBasePath(href), window.location.href)\n    return true\n  } catch {\n    return false\n  }\n}","typeGuard":"function isParsableUrl(href: string, base?: string): href is string {\n  try {\n    new URL(href, base ?? window.location.href)\n    return true\n  } catch {\n    return false\n  }\n}","tryCatchPattern":"try {\n  router.prefetch(href)\n} catch (e) {\n  if (e.message.includes('cannot be converted to a URL')) {\n    console.warn('Skipping invalid prefetch href:', href)\n    return\n  }\n  throw e\n}","preventionTips":["URL-encode all dynamic query parameters with encodeURIComponent.","Validate hrefs with a URL constructor check before passing to Link or prefetch.","Filter out undefined/null/empty href values from dynamic link data."],"tags":["router","prefetch","url-validation","link","app-router"],"analyzedSha":"0ae8c72462952df163f1b1e0726641bc5b40dc93","analyzedAt":"2026-08-06T19:44:29.143Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}