EC
ERR_FS_INVALID_SCHEME
Node.jsERRORNotableFilesystemHIGH confidence

File URL has an invalid or unsupported scheme

Production Risk

Low — caught immediately at call site.

What this means

Thrown when a URL passed to a filesystem API uses a scheme other than "file:". Node.js filesystem APIs only accept file: URLs or plain path strings; other URL schemes such as http: or data: are not supported.

Why it happens
  1. 1Passing an http:// or https:// URL to fs.readFile() or similar APIs
  2. 2Using a data: URL as a file path
  3. 3Misconfigured path generation code that produces non-file URLs
How to reproduce

Triggered when an fs API receives a URL object whose scheme is not "file:".

trigger — this will error
trigger — this will error
const fs = require('fs');
const url = new URL('https://example.com/data.json');
fs.readFile(url, 'utf8', (err) => {
  console.error(err.code); // ERR_FS_INVALID_SCHEME
});

expected output

TypeError [ERR_FS_INVALID_SCHEME]: Only "file:" URLs are supported for file system operations

Fix 1

Use a file: URL or a plain path string

WHEN When passing paths to fs APIs

Use a file: URL or a plain path string
const fs = require('fs');
const { fileURLToPath } = require('url');

// Using a file URL
const url = new URL('file:///home/user/data.json');
fs.readFile(fileURLToPath(url), 'utf8', (err, data) => {
  console.log(data);
});

Why this works

fileURLToPath() converts a valid file: URL to a platform-specific path string.

Fix 2

Fetch remote resources separately and write to a temp file

WHEN When you actually need data from an HTTP URL

Fetch remote resources separately and write to a temp file
const https = require('https');
const fs = require('fs');
const tmp = '/tmp/remote-data.json';
const file = fs.createWriteStream(tmp);
https.get('https://example.com/data.json', (res) => res.pipe(file));

Why this works

Streaming HTTP response to a local file separates remote fetch from filesystem access.

Code examples
Triggerjs
const fs = require('fs');
const url = new URL('https://example.com/data.json');
fs.readFile(url, 'utf8', (err) => {
  console.error(err.code); // ERR_FS_INVALID_SCHEME
});  // this triggers ERR_FS_INVALID_SCHEME
Handle in try/catchjs
try {
  // operation that may throw ERR_FS_INVALID_SCHEME
  riskyOperation()
} catch (err) {
  if (err.code === 'ERR_FS_INVALID_SCHEME') {
    console.error('ERR_FS_INVALID_SCHEME:', err.message)
  } else {
    throw err
  }
}
Defensive pattern to avoid itjs
// Validate inputs before calling the operation
function safe_err_fs_invalid_scheme(...args) {
  // validate args here
  return performOperation(...args)
}
What not to do

✕ Pass http: or https: URLs to fs functions

fs only understands file: URLs and path strings; non-file schemes are always rejected.

Same error in other languages
ValueErrorin Python→
Sources
Official documentation ↗

Node.js Error Codes Documentation

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Node.js errors