url: add err.input to ERR_INVALID_FILE_URL_PATH

joyeecheung · richardlau · commit ba5b6597aa64 · 2025-09-20T06:16:57.000Z
Otherwise there's no information from the error about what exactly is the invalid URL. PR-URL: #59730 Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com> Reviewed-By: Anna Henningsen <anna@addaleax.net>
diff --git a/doc/api/errors.md b/doc/api/errors.md
@@ -1992,6 +1992,9 @@ A Node.js API that consumes `file:` URLs (such as certain functions in the
 [`fs`][] module) encountered a file URL with an incompatible path. The exact
 semantics for determining whether a path can be used is platform-dependent.
 
+The thrown error object includes an `input` property that contains the URL object
+of the invalid `file:` URL.
+
 <a id="ERR_INVALID_HANDLE_TYPE"></a>
 
 ### `ERR_INVALID_HANDLE_TYPE`
diff --git a/lib/internal/errors.js b/lib/internal/errors.js
@@ -1476,7 +1476,10 @@ E('ERR_INVALID_FD',
 E('ERR_INVALID_FD_TYPE', 'Unsupported fd type: %s', TypeError);
 E('ERR_INVALID_FILE_URL_HOST',
   'File URL host must be "localhost" or empty on %s', TypeError);
-E('ERR_INVALID_FILE_URL_PATH', 'File URL path %s', TypeError);
+E('ERR_INVALID_FILE_URL_PATH', function(reason, input) {
+  this.input = input;
+  return `File URL path ${reason}`;
+}, TypeError);
 E('ERR_INVALID_HANDLE_TYPE', 'This handle type cannot be sent', TypeError);
 E('ERR_INVALID_HTTP_TOKEN', '%s must be a valid HTTP token ["%s"]', TypeError, HideStackFramesError);
 E('ERR_INVALID_IP_ADDRESS', 'Invalid IP address: %s', TypeError);
diff --git a/lib/internal/url.js b/lib/internal/url.js
@@ -1462,7 +1462,7 @@ function getPathFromURLWin32(url) {
       if ((pathname[n + 1] === '2' && third === 102) || // 2f 2F /
           (pathname[n + 1] === '5' && third === 99)) {  // 5c 5C \
         throw new ERR_INVALID_FILE_URL_PATH(
-          'must not include encoded \\ or / characters',
+          'must not include encoded \\ or / characters', url,
         );
       }
     }
@@ -1483,7 +1483,7 @@ function getPathFromURLWin32(url) {
   const sep = StringPrototypeCharAt(pathname, 2);
   if (letter < CHAR_LOWERCASE_A || letter > CHAR_LOWERCASE_Z ||   // a..z A..Z
       (sep !== ':')) {
-    throw new ERR_INVALID_FILE_URL_PATH('must be absolute');
+    throw new ERR_INVALID_FILE_URL_PATH('must be absolute', url);
   }
   return StringPrototypeSlice(pathname, 1);
 }
@@ -1550,7 +1550,7 @@ function getPathBufferFromURLWin32(url) {
 
   if (letter < CHAR_LOWERCASE_A || letter > CHAR_LOWERCASE_Z ||   // a..z A..Z
       (sep !== CHAR_COLON)) {
-    throw new ERR_INVALID_FILE_URL_PATH('must be absolute');
+    throw new ERR_INVALID_FILE_URL_PATH('must be absolute', url);
   }
 
   // Now, we'll just return everything except the first byte of
@@ -1569,6 +1569,7 @@ function getPathFromURLPosix(url) {
       if (pathname[n + 1] === '2' && third === 102) {
         throw new ERR_INVALID_FILE_URL_PATH(
           'must not include encoded / characters',
+          url,
         );
       }
     }
diff --git a/test/parallel/test-url-fileurltopath.js b/test/parallel/test-url-fileurltopath.js
@@ -31,24 +31,6 @@ test('fileURLToPath with host', () => {
   }
 });
 
-test('fileURLToPath with invalid path', () => {
-  if (isWindows) {
-    assert.throws(() => url.fileURLToPath('file:///C:/a%2F/'), {
-      code: 'ERR_INVALID_FILE_URL_PATH'
-    });
-    assert.throws(() => url.fileURLToPath('file:///C:/a%5C/'), {
-      code: 'ERR_INVALID_FILE_URL_PATH'
-    });
-    assert.throws(() => url.fileURLToPath('file:///?:/'), {
-      code: 'ERR_INVALID_FILE_URL_PATH'
-    });
-  } else {
-    assert.throws(() => url.fileURLToPath('file:///a%2F/'), {
-      code: 'ERR_INVALID_FILE_URL_PATH'
-    });
-  }
-});
-
 const windowsTestCases = [
   // Lowercase ascii alpha
   { path: 'C:\\foo', fileURL: 'file:///C:/foo' },
diff --git a/test/parallel/test-url-invalid-file-url-path-input.js b/test/parallel/test-url-invalid-file-url-path-input.js
@@ -0,0 +1,25 @@
+'use strict';
+
+// This tests that url.fileURLToPath() throws ERR_INVALID_FILE_URL_PATH
+// for invalid file URL paths along with the input property.
+
+const { isWindows } = require('../common');
+const assert = require('assert');
+const url = require('url');
+
+const inputs = [];
+
+if (isWindows) {
+  inputs.push('file:///C:/a%2F/', 'file:///C:/a%5C/', 'file:///?:/');
+} else {
+  inputs.push('file:///a%2F/');
+}
+
+for (const input of inputs) {
+  assert.throws(() => url.fileURLToPath(input), (err) => {
+    assert.strictEqual(err.code, 'ERR_INVALID_FILE_URL_PATH');
+    assert(err.input instanceof URL);
+    assert.strictEqual(err.input.href, input);
+    return true;
+  });
+}

Original file line number	Diff line number	Diff line change
`@@ -1462,7 +1462,7 @@ function getPathFromURLWin32(url) {`
`1462`	`1462`	`if ((pathname[n + 1] === '2' && third === 102) \|\| // 2f 2F /`
`1463`	`1463`	`(pathname[n + 1] === '5' && third === 99)) { // 5c 5C \`
`1464`	`1464`	`throw new ERR_INVALID_FILE_URL_PATH(`
`1465`		`- 'must not include encoded \\ or / characters',`
	`1465`	`+ 'must not include encoded \\ or / characters', url,`
`1466`	`1466`	`);`
`1467`	`1467`	`}`
`1468`	`1468`	`}`
`@@ -1483,7 +1483,7 @@ function getPathFromURLWin32(url) {`
`1483`	`1483`	`const sep = StringPrototypeCharAt(pathname, 2);`
`1484`	`1484`	`if (letter < CHAR_LOWERCASE_A \|\| letter > CHAR_LOWERCASE_Z \|\| // a..z A..Z`
`1485`	`1485`	`(sep !== ':')) {`
`1486`		`- throw new ERR_INVALID_FILE_URL_PATH('must be absolute');`
	`1486`	`+ throw new ERR_INVALID_FILE_URL_PATH('must be absolute', url);`
`1487`	`1487`	`}`
`1488`	`1488`	`return StringPrototypeSlice(pathname, 1);`
`1489`	`1489`	`}`
`@@ -1550,7 +1550,7 @@ function getPathBufferFromURLWin32(url) {`
`1550`	`1550`
`1551`	`1551`	`if (letter < CHAR_LOWERCASE_A \|\| letter > CHAR_LOWERCASE_Z \|\| // a..z A..Z`
`1552`	`1552`	`(sep !== CHAR_COLON)) {`
`1553`		`- throw new ERR_INVALID_FILE_URL_PATH('must be absolute');`
	`1553`	`+ throw new ERR_INVALID_FILE_URL_PATH('must be absolute', url);`
`1554`	`1554`	`}`
`1555`	`1555`
`1556`	`1556`	`// Now, we'll just return everything except the first byte of`
`@@ -1569,6 +1569,7 @@ function getPathFromURLPosix(url) {`
`1569`	`1569`	`if (pathname[n + 1] === '2' && third === 102) {`
`1570`	`1570`	`throw new ERR_INVALID_FILE_URL_PATH(`
`1571`	`1571`	`'must not include encoded / characters',`
	`1572`	`+ url,`
`1572`	`1573`	`);`
`1573`	`1574`	`}`
`1574`	`1575`	`}`