facebook/docusaurus · error

Can't parse URL ${str}${base ? ` with base ${base}` : ''}

Error message

Can't parse URL ${str}${base ? ` with base ${base}` : ''}

What it means

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.

Source

Thrown at packages/docusaurus-utils/src/urlUtils.ts:172

 */
export function isValidPathname(str: string): boolean {
  if (!str.startsWith('/')) {
    return false;
  }
  const url = URL.parse(str, 'https://domain.com');
  if (url === null) {
    return false;
  }
  const parsedPathname = url.pathname;
  return parsedPathname === str || parsedPathname === encodeURI(str);
}

export function parseURLOrPath(str: string, base?: string | URL): URL {
  const url = URL.parse(str, base ?? 'https://example.com');
  if (url) {
    return url;
  }
  throw new Error(`Can't parse URL ${str}${base ? ` with base ${base}` : ''}`);
}

export type URLPath = {pathname: string; search?: string; hash?: string};

export function toURLPath(url: URL): URLPath {
  const {pathname} = url;

  // Fixes annoying url.search behavior
  // "" => undefined
  // "?" => ""
  // "?param => "param"
  const search = url.search
    ? url.search.slice(1)
    : url.href.includes('?')
      ? ''
      : undefined;

  // Fixes annoying url.hash behavior

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Inspect the str (and base) echoed in the error message for illegal characters, unencoded spaces, or malformed bracket notation.
2. Sanitize the input with encodeURI / encodeURIComponent as appropriate, or trim whitespace, before parsing.
3. 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.
4. Validate user-supplied URLs at the config boundary (e.g. with a Joi string().uri() schema) so the error surfaces with a clearer pointer.

Example fix

// before
const u = parseURLOrPath(rawUserInput);

// after
const trimmed = rawUserInput.trim();
if (!URL.canParse(trimmed)) {
  throw new Error(`Invalid URL in config: ${rawUserInput}`);
}
const u = parseURLOrPath(trimmed);

function canParseUrl(str: string, base?: string | URL): boolean {
  try { URL.parse(str, base ?? 'https://example.com'); return true; }
  catch { return false; }
}

if (!canParseUrl(rawUserInput)) {
  throw new Error(`Invalid URL provided: ${rawUserInput}`);
}

function isParseableUrl(str: string, base?: string | URL): boolean {
  try { URL.parse(str, base ?? 'https://example.com'); return true; }
  catch { return false; }
}

try {
  parseURLOrPath(str, base);
} catch (err) {
  if (err instanceof Error && err.message.startsWith("Can't parse URL")) {
    // sanitize (trim, encodeURI) and retry, or fall back to a safe default
  }
  throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Url must be a string. Received ${typeof component}
• Invalid command: ${command}
• Invalid package manager choice ${packageManager}. Must be on
• Directory already exists at path=${dest}!
• Error while attempting to extract Docusaurus translations fr

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/d0ed2fae7aca8cbc. Report an issue: GitHub.