Maaz Zindani

Loading the index…

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

Node.js says require() of an ES Module is not supported

ErrorError [ERR_REQUIRE_ESM]: require() of ES Module /app/node_modules/some-package/index.js not supported.

Short answer

The file you require() is an ES module. On Node.js 22.12, 20.19 and newer, require() loads most ES modules without a flag, so first check your Node.js version. If the module uses top-level await, require() cannot load it at all: use import() instead, or move your own code to ESM.

  • Applies to Node.js 20.19, Node.js 22.12, Node.js 24
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the Node.js version that actually runs the app, and whether it has require(esm). The second value is true when require() can load ES modules.

    node -p "process.version + ' ' + process.features.require_module"
  2. 2Match what you see, then jump to its fix

    1. 1ERR_REQUIRE_ESM and the version printed above is below 20.19 or below 22.12Node.js is older than the release where require(esm) became defaultFix
    2. 2ERR_REQUIRE_ASYNC_MODULE on a Node.js version that supports require(esm)The imported package or file uses top-level awaitFix
    3. 3ERR_REQUIRE_ESM from a package that dropped CommonJS, on Node.js that cannot be upgradedYour code is CommonJS and needs an old version of the ESM-only packageFix

What does the error look like?

  • Error [ERR_REQUIRE_ESM]: require() of ES Module /app/node_modules/some-package/index.js not supported.
  • Error [ERR_REQUIRE_ASYNC_MODULE]

Cause 1 of 3

Node.js is older than the release where require(esm) became default

1Check

Compare the printed version with the table in the Node.js modules docs. require() of an ES module works without a flag from v20.19.0, v22.12.0 and v23.0.0.

node --version
node -p "process.features.require_module"

2Fix

Upgrade Node.js to a release that supports it. On servers, also check which binary your process manager starts, because it may not be the one in your shell.

# with nvm
nvm install 22
nvm use 22

3Verify

The feature flag prints true and the app starts.

node -p "process.features.require_module"
node index.js

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 3

The imported package or file uses top-level await

1Check

require() only loads an ES module that is fully synchronous. One top-level await anywhere in its import graph is enough to fail. Node.js can print where the awaits are.

node --experimental-print-required-tla index.js

2Fix

Load that module with a dynamic import() inside an async function, instead of require().

// Instead of: const mod = require('./async-module.mjs');
async function main() {
  const mod = await import('./async-module.mjs');
  // use mod here
}
main();

3Verify

Start the app again. The error is gone and the module is usable.

node index.js

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 3

Your code is CommonJS and needs an old version of the ESM-only package

1Check

Look at the package's package.json: "type": "module" or an exports map with only an import condition means it ships ES modules only.

node -p "const p=require('./node_modules/some-package/package.json'); p.type"

2Fix

Use dynamic import() for that package, or switch your own project to ES modules by setting "type": "module" in package.json and using import statements.

// package.json
{ "type": "module" }

// index.js
import something from 'some-package';

3Verify

Run the entry file. Node.js loads it as an ES module and the error does not appear.

node index.js

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Pin the Node.js version in package.json engines and in your Dockerfile or deploy config, so the server runs the same version as your machine.
  • Before upgrading a dependency, read its release notes for the words ESM only or dropped CommonJS.
  • Avoid top-level await in modules that CommonJS code may need to require.

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.