{"record":{"id":"10071ecf4ed2626e","repo":"denoland/deno","slug":"err-invalid-file-url-host","errorCode":"ERR_INVALID_FILE_URL_HOST","errorMessage":"File URL host must be \"localhost\" or empty on ${osType}","messagePattern":"File URL host must be \"localhost\" or empty on (.+?)","errorType":"error_code","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"ext/node/polyfills/url.ts","lineNumber":1449,"sourceCode":"  path: string | URL,\n  options: { windows?: boolean } = { __proto__: null },\n) {\n  const windows = options?.windows;\n  if (typeof path === \"string\") path = new URL(path);\n  else if (!ObjectPrototypeIsPrototypeOf(URL.prototype, path)) {\n    throw new ERR_INVALID_ARG_TYPE(\"path\", [\"string\", \"URL\"], path);\n  }\n  if (path.protocol !== \"file:\") {\n    throw new ERR_INVALID_URL_SCHEME(\"file\");\n  }\n  return (windows ?? isWindows)\n    ? getPathBufferFromURLWin(path)\n    : getPathBufferFromURLPosix(path);\n}\n\nfunction getPathBufferFromURLPosix(url: URL) {\n  if (url.hostname !== \"\") {\n    throw new ERR_INVALID_FILE_URL_HOST(osType);\n  }\n  const Buffer = lazyBuffer();\n  const u8 = percentDecode(Buffer.from(url.pathname, \"utf8\"));\n  return Buffer.from(\n    TypedArrayPrototypeGetBuffer(u8),\n    TypedArrayPrototypeGetByteOffset(u8),\n    TypedArrayPrototypeGetByteLength(u8),\n  );\n}\n\nfunction getPathBufferFromURLWin(url: URL) {\n  const Buffer = lazyBuffer();\n  const hostname = url.hostname;\n  const pathname = StringPrototypeReplace(\n    url.pathname,\n    forwardSlashRegEx,\n    \"\\\\\",\n  );","sourceCodeStart":1431,"sourceCodeEnd":1467,"githubUrl":"https://github.com/denoland/deno/blob/9ad36f7a2cce60488e6ec52283efb32efddaf93a/ext/node/polyfills/url.ts#L1431-L1467","documentation":"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.","triggerScenarios":"`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.","commonSituations":"Cross-platform configuration holding Windows UNC file URLs; CI matrices running on Linux fixtures authored on Windows.","solutions":["Translate the host to a mount point yourself (file://nas/share/f becomes /mnt/nas/share/f)","Check `url.hostname === ''` before converting","Normalize per-platform path configuration at load time"],"exampleFix":"// before\nconst buf = fileURLToPathBuffer(new URL(cfg.fileUrl)); // file://nas/share/x on Linux\n\n// after\nconst u = new URL(cfg.fileUrl);\nconst buf = u.hostname\n  ? Buffer.from(path.join(\"/mnt\", u.hostname, u.pathname)) // map UNC to mount\n  : fileURLToPathBuffer(u);","handlingStrategy":"validation","validationCode":"const u = typeof input === \"string\" ? new URL(input) : input;\nif (u.hostname !== \"\") {\n  throw new Error(`file URL host '${u.hostname}' cannot map to a POSIX path; translate to a mount point`);\n}\nreturn fileURLToPathBuffer(u);","typeGuard":"const isLocalFileUrl = (u: URL): boolean =>\n  u.protocol === \"file:\" && u.hostname === \"\";","tryCatchPattern":"try {\n  buf = fileURLToPathBuffer(u);\n} catch (e: any) {\n  if (e?.code === \"ERR_INVALID_FILE_URL_HOST\") {\n    buf = Buffer.from(path.join(\"/mnt\", u.hostname, u.pathname)); // UNC to mount\n  } else {\n    throw e;\n  }\n}","preventionTips":["Reject or translate file URLs with hosts before POSIX conversion","Normalize path config per platform at load time","Remember file://localhost is also rejected on POSIX"],"tags":["file-url","posix","unc","node-compat"],"backgroundTag":"file-url-host-mismatch","analyzedSha":"9ad36f7a2cce60488e6ec52283efb32efddaf93a","analyzedAt":"2026-08-20T13:07:44.778Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}