denoland/deno · error · TypeError

ERR_INVALID_FILE_URL_HOST

ERR_INVALID_FILE_URL_HOST

Error message

File URL host must be "localhost" or empty on ${osType}

What it means

On POSIX, getPathBufferFromURLPosix rejects any file URL with a non-empty hostname — including localhost — with ERR_INVALID_FILE_URL_HOST, because POSIX paths cannot express a remote host; hosts are a Windows UNC concept (file://server/share). Note the message text mentions localhost, but the code rejects every non-empty host on POSIX.

Source

Thrown at ext/node/polyfills/url.ts:1449

  path: string | URL,
  options: { windows?: boolean } = { __proto__: null },
) {
  const windows = options?.windows;
  if (typeof path === "string") path = new URL(path);
  else if (!ObjectPrototypeIsPrototypeOf(URL.prototype, path)) {
    throw new ERR_INVALID_ARG_TYPE("path", ["string", "URL"], path);
  }
  if (path.protocol !== "file:") {
    throw new ERR_INVALID_URL_SCHEME("file");
  }
  return (windows ?? isWindows)
    ? getPathBufferFromURLWin(path)
    : getPathBufferFromURLPosix(path);
}

function getPathBufferFromURLPosix(url: URL) {
  if (url.hostname !== "") {
    throw new ERR_INVALID_FILE_URL_HOST(osType);
  }
  const Buffer = lazyBuffer();
  const u8 = percentDecode(Buffer.from(url.pathname, "utf8"));
  return Buffer.from(
    TypedArrayPrototypeGetBuffer(u8),
    TypedArrayPrototypeGetByteOffset(u8),
    TypedArrayPrototypeGetByteLength(u8),
  );
}

function getPathBufferFromURLWin(url: URL) {
  const Buffer = lazyBuffer();
  const hostname = url.hostname;
  const pathname = StringPrototypeReplace(
    url.pathname,
    forwardSlashRegEx,
    "\\",
  );

View on GitHub (pinned to 9ad36f7a2c)

Solutions

1. Translate the host to a mount point yourself (file://nas/share/f becomes /mnt/nas/share/f)
2. Check `url.hostname === ''` before converting
3. Normalize per-platform path configuration at load time

Example fix

// before
const buf = fileURLToPathBuffer(new URL(cfg.fileUrl)); // file://nas/share/x on Linux

// after
const u = new URL(cfg.fileUrl);
const buf = u.hostname
  ? Buffer.from(path.join("/mnt", u.hostname, u.pathname)) // map UNC to mount
  : fileURLToPathBuffer(u);

const u = typeof input === "string" ? new URL(input) : input;
if (u.hostname !== "") {
  throw new Error(`file URL host '${u.hostname}' cannot map to a POSIX path; translate to a mount point`);
}
return fileURLToPathBuffer(u);

const isLocalFileUrl = (u: URL): boolean =>
  u.protocol === "file:" && u.hostname === "";

try {
  buf = fileURLToPathBuffer(u);
} catch (e: any) {
  if (e?.code === "ERR_INVALID_FILE_URL_HOST") {
    buf = Buffer.from(path.join("/mnt", u.hostname, u.pathname)); // UNC to mount
  } else {
    throw e;
  }
}

When it happens

Trigger: `fileURLToPathBuffer(new URL('file://nas/share/doc.pdf'))` on Linux/macOS; a file://localhost/x URL; UNC file URLs written on Windows and consumed by POSIX builds.

Common situations: Cross-platform configuration holding Windows UNC file URLs; CI matrices running on Linux fixtures authored on Windows.

Related errors

• ERR_INVALID_ARG_TYPE
• ERR_INVALID_URL_SCHEME
• ERR_INVALID_FILE_URL_PATH
• ERR_INVALID_ARG_VALUE
• Host must be empty

AI-assisted analysis of denoland/deno@9ad36f7a2c (2026-08-20). Data as JSON: /api/errors/10071ecf4ed2626e. Report an issue: GitHub.