{"record":{"id":"d0ed2fae7aca8cbc","repo":"facebook/docusaurus","slug":"can-t-parse-url-str-base-with-base-base","errorCode":null,"errorMessage":"Can't parse URL ${str}${base ? ` with base ${base}` : ''}","messagePattern":"Can't parse URL (.+?)(.+?)` : ''\\}","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/docusaurus-utils/src/urlUtils.ts","lineNumber":172,"sourceCode":" */\nexport function isValidPathname(str: string): boolean {\n  if (!str.startsWith('/')) {\n    return false;\n  }\n  const url = URL.parse(str, 'https://domain.com');\n  if (url === null) {\n    return false;\n  }\n  const parsedPathname = url.pathname;\n  return parsedPathname === str || parsedPathname === encodeURI(str);\n}\n\nexport function parseURLOrPath(str: string, base?: string | URL): URL {\n  const url = URL.parse(str, base ?? 'https://example.com');\n  if (url) {\n    return url;\n  }\n  throw new Error(`Can't parse URL ${str}${base ? ` with base ${base}` : ''}`);\n}\n\nexport type URLPath = {pathname: string; search?: string; hash?: string};\n\nexport function toURLPath(url: URL): URLPath {\n  const {pathname} = url;\n\n  // Fixes annoying url.search behavior\n  // \"\" => undefined\n  // \"?\" => \"\"\n  // \"?param => \"param\"\n  const search = url.search\n    ? url.search.slice(1)\n    : url.href.includes('?')\n      ? ''\n      : undefined;\n\n  // Fixes annoying url.hash behavior","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-utils/src/urlUtils.ts#L154-L190","documentation":"Thrown by parseURLOrPath() when URL.parse() returns null for the given input (and base, defaulting to 'https://example.com'). URL.parse returning null indicates the input is not a parseable URL or relative reference. The error echoes the input string and base if one was provided.","triggerScenarios":"Calling parseURLOrPath(str, base?) where str is a malformed URL or an invalid relative reference under the provided base. URL.parse is stricter than deprecated constructors; inputs containing illegal characters or structural violations (e.g. stray spaces, malformed brackets, invalid percent-encoding) cause a null return.","commonSituations":"User-supplied permalink or href with a typo (space in the middle, unencoded bracket). Reading a URL from front matter that was not validated. Programmatic concatenation that produced an invalid reference. A base URL that is itself invalid.","solutions":["Inspect the str (and base) echoed in the error message for illegal characters, unencoded spaces, or malformed bracket notation.","Sanitize the input with encodeURI / encodeURIComponent as appropriate, or trim whitespace, before parsing.","If the input may legitimately be unparseable, wrap the call in try/catch and fall back to a safe default rather than crashing the build.","Validate user-supplied URLs at the config boundary (e.g. with a Joi string().uri() schema) so the error surfaces with a clearer pointer."],"exampleFix":"// before\nconst u = parseURLOrPath(rawUserInput);\n\n// after\nconst trimmed = rawUserInput.trim();\nif (!URL.canParse(trimmed)) {\n  throw new Error(`Invalid URL in config: ${rawUserInput}`);\n}\nconst u = parseURLOrPath(trimmed);","handlingStrategy":"validation","validationCode":"function canParseUrl(str: string, base?: string | URL): boolean {\n  try { URL.parse(str, base ?? 'https://example.com'); return true; }\n  catch { return false; }\n}\n\nif (!canParseUrl(rawUserInput)) {\n  throw new Error(`Invalid URL provided: ${rawUserInput}`);\n}","typeGuard":"function isParseableUrl(str: string, base?: string | URL): boolean {\n  try { URL.parse(str, base ?? 'https://example.com'); return true; }\n  catch { return false; }\n}","tryCatchPattern":"try {\n  parseURLOrPath(str, base);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith(\"Can't parse URL\")) {\n    // sanitize (trim, encodeURI) and retry, or fall back to a safe default\n  }\n  throw err;\n}","preventionTips":["Trim and encode user-supplied URLs before parsing.","Validate URL-shaped config fields with Joi string().uri() at the config boundary.","When the input may legitimately be unparseable, wrap parseURLOrPath in try/catch and degrade gracefully."],"tags":["url","parsing","validation"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}