Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

ERR_UNSUPPORTED_ESM_URL_SCHEME when Node.js imports a file

ErrorError [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only file and data URLs are supported by the default ESM loader

Short answer

Node.js treats an import specifier that is not relative or bare as a URL. A Windows path such as C:\app\config.js reads as a URL with the scheme c:, and Node only accepts file: and data:. Convert the path with url.pathToFileURL before importing it. Importing an https address needs a custom loader.

  • Applies to Node.js 22, Windows 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find what string reaches import(). The error message names the scheme Node found; match it against the two causes below.

    node -v
    grep -rn "import(" .
  2. 2Match what you see, then jump to its fix

    1. 1The scheme in the message is a single letter, which is the drive letter, and the code runs on Windows.A Windows absolute path was passed to import()Fix
    2. 2The message names https or http as the scheme.The specifier is an https: addressFix

What does the error look like?

  • Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only file and data URLs are supported by the default ESM loader
  • import with URL schemes other than file and data is unsupported

Cause 1 of 2

A Windows absolute path was passed to import()

1Check

Search your own code and any config loader for import() calls that receive a path built with path.resolve or path.join.

grep -rn "import(" src scripts

2Fix

Node resolves absolute specifiers as file: URLs and recommends url.pathToFileURL for paths. Convert the path first, then import its href.

import { pathToFileURL } from 'node:url';
import path from 'node:path';

const file = path.resolve('config', 'app.config.js');
const mod = await import(pathToFileURL(file).href);

3Verify

The same call now loads the module on Windows and on Linux.

node load-config.mjs

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 2

The specifier is an https: address

1Check

Look for imports that start with https://, for example a script pulled straight from a CDN.

grep -rn "from 'http\|import('http" src

2Fix

Node does not load such specifiers natively. Download the file at build time and import the local copy, install the package from npm, or write a custom loader that handles https.

npm install the-package
# then
import something from 'the-package';

3Verify

Run the script again; the import resolves from node_modules.

node app.mjs

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Never pass a raw file system path to import(); pass a file URL.
  • Keep dependencies in package.json instead of importing code from a URL at runtime.
  • Run your tooling on Windows once in CI if developers use it.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.