{"record":{"id":"84edca46423e2347","repo":"denoland/deno","slug":"err-invalid-file-url-path","errorCode":"ERR_INVALID_FILE_URL_PATH","errorMessage":"File URL path must be absolute","messagePattern":"File URL path must be absolute","errorType":"error_code","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"ext/node/polyfills/url.ts","lineNumber":1488,"sourceCode":"    TypedArrayPrototypeGetBuffer(u8),\n    TypedArrayPrototypeGetByteOffset(u8),\n    TypedArrayPrototypeGetByteLength(u8),\n  );\n  if (hostname !== \"\") {\n    const prefix = Buffer.from(\"\\\\\\\\\", \"ascii\");\n    const domain = Buffer.from(domainToUnicode(hostname), \"utf8\");\n    // `concat` is a `node:buffer` static method on `Buffer`\n    // deno-lint-ignore deno-internal/prefer-primordials\n    return Buffer.concat([prefix, domain, decodedPathname]);\n  }\n  const letter = decodedPathname[1] | 0x20;\n  const sep = decodedPathname[2];\n  if (\n    letter < CHAR_LOWERCASE_A ||\n    letter > CHAR_LOWERCASE_Z || // a..z A..Z\n    sep !== 0x3a // :\n  ) {\n    throw new ERR_INVALID_FILE_URL_PATH(\"must be absolute\", url);\n  }\n  return TypedArrayPrototypeSubarray(decodedPathname, 1);\n}\n\nfunction getPathFromURLWin(url: URL): string {\n  const hostname = url.hostname;\n  let pathname = url.pathname;\n  for (let n = 0; n < pathname.length; n++) {\n    if (pathname[n] === \"%\") {\n      const third = StringPrototypeCodePointAt(pathname, n + 2)! | 0x20;\n      if (\n        (pathname[n + 1] === \"2\" && third === 102) || // 2f 2F /\n        (pathname[n + 1] === \"5\" && third === 99) // 5c 5C \\\n      ) {\n        throw new ERR_INVALID_FILE_URL_PATH(\n          \"must not include encoded \\\\ or / characters\",\n          url,\n        );","sourceCodeStart":1470,"sourceCodeEnd":1506,"githubUrl":"https://github.com/denoland/deno/blob/9ad36f7a2cce60488e6ec52283efb32efddaf93a/ext/node/polyfills/url.ts#L1470-L1506","documentation":"In the Windows branch of fileURLToPathBuffer, the percent-decoded pathname must be shaped like /<drive-letter>:/rest (e.g. /C:/Users): byte 1 an ASCII letter (case-insensitive), byte 2 a colon. File URLs without a drive letter throw ERR_INVALID_FILE_URL_PATH 'must be absolute', since no absolute Windows path can be formed from them.","triggerScenarios":"`fileURLToPathBuffer(new URL('file:///tmp/a'), { windows: true })`; POSIX-shaped file URLs forced through the windows code path; relative `file:../x` URLs.","commonSituations":"Cross-platform tools forcing `{ windows: true }` to precompute Windows byte paths; build pipelines emitting POSIX file URLs consumed by Windows logic.","solutions":["Only use `{ windows: true }` with drive-letter URLs (file:///C:/...)","Build URLs from real Windows paths with pathToFileURL() so the drive letter is present","Branch on process.platform instead of forcing windows semantics"],"exampleFix":"// before\nconst buf = fileURLToPathBuffer(new URL(\"file:///tmp/a\"), { windows: true }); // throws\n\n// after\nimport { pathToFileURL } from \"node:url\";\nconst url = pathToFileURL(\"C:/tmp/a\"); // carries a drive letter\nconst buf = fileURLToPathBuffer(url, { windows: true });","handlingStrategy":"validation","validationCode":"const u = new URL(input);\nif (windows && !/^\\/[a-zA-Z]:/.test(u.pathname)) {\n  throw new Error(\"Windows file URLs need a drive letter, e.g. file:///C:/x\");\n}\nreturn fileURLToPathBuffer(u, { windows });","typeGuard":"const hasDriveLetter = (u: URL): boolean => /^\\/[a-zA-Z]:/.test(u.pathname);","tryCatchPattern":"try {\n  buf = fileURLToPathBuffer(u, { windows: true });\n} catch (e: any) {\n  if (e?.code === \"ERR_INVALID_FILE_URL_PATH\") {\n    buf = fileURLToPathBuffer(pathToFileURL(winPath), { windows: true });\n  } else {\n    throw e;\n  }\n}","preventionTips":["Force { windows: true } only for URLs built from Windows absolute paths","Create URLs with pathToFileURL() so drive letters are present","Branch on process.platform instead of hardcoding windows semantics"],"tags":["file-url","windows","drive-letter","node-compat"],"backgroundTag":"invalid-file-url-path","analyzedSha":"9ad36f7a2cce60488e6ec52283efb32efddaf93a","analyzedAt":"2026-08-20T13:07:44.778Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}