Maaz Zindani

Loading the index…

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

require() of an ES module fails in a cycle or with top-level await

ErrorError [ERR_REQUIRE_CYCLE_MODULE]

Short answer

Since Node.js 22.12 and 20.19, require() can load an ES module, but only if the module graph has no top-level await and no immediate cycle. ERR_REQUIRE_CYCLE_MODULE means a cycle, so require lazily inside a function. ERR_REQUIRE_ASYNC_MODULE means top-level await, so load that module with import().

  • Applies to 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 and ask Node.js to point at any top-level await in the graph. The flag only prints locations when the error is uncaught.

    node -v
    node --experimental-print-required-tla app.js
  2. 2Match what you see, then jump to its fix

    1. 1ERR_REQUIRE_CYCLE_MODULE, and the files named in the stack trace import each other, directly or through a third fileTwo modules require each other at the top levelFix
    2. 2ERR_REQUIRE_ASYNC_MODULEThe ES module, or something it imports, uses top-level awaitFix
    3. 3The same code works on Node.js 22.12+ or 24 but fails on an older machine, CI image or containerNode.js is older than the release that supports require(esm)Fix

What does the error look like?

  • Error [ERR_REQUIRE_CYCLE_MODULE]
  • Error [ERR_REQUIRE_ASYNC_MODULE]

Cause 1 of 3

Two modules require each other at the top level

1Check

Draw the chain from the stack trace: file A requires an ES module B, and B (or something B imports) leads back to A while A is still being evaluated. An ES module cannot be evaluated while it is already being evaluated.

node app.js 2>&1 | head -n 20

2Fix

Do not call require() at the top level of either side of the cycle. Move the call into the function that needs it so it runs after both modules finished loading.

// a.cjs
function useB() {
  const b = require('./b.mjs'); // lazy: runs when called, not at load
  return b.run();
}
module.exports = { useB };

3Verify

Start the app again and call the function that needed the module.

node -e "console.log(require('./a.cjs').useB())"

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 3

The ES module, or something it imports, uses top-level await

1Check

Only fully synchronous ES modules can be loaded with require(). Run the check from the first step to see where the await sits.

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

2Fix

Load the asynchronous module with dynamic import(), which returns a promise, and use it after the promise resolves.

// CommonJS file
async function main() {
  const mod = await import('./settings.mjs');
  console.log(mod.default);
}
main();

3Verify

Run the file; the module loads without the error.

node app.cjs

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 3

Node.js is older than the release that supports require(esm)

1Check

The feature was added in v22.0.0 and v20.17.0 behind a flag, and stopped needing the flag in v22.12.0 and v20.19.0. Check the version on the machine that fails.

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

2Fix

Update Node.js to 22.12 or newer (or 20.19 or newer), and make the CI image and Dockerfile use it. If you cannot upgrade, load the module with import().

# .nvmrc
22

3Verify

process.features.require_module prints true.

node -p "process.features.require_module"

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Keep the same Node.js major version on laptops, CI and production, and write it in .nvmrc.
  • Avoid top-level await in modules that CommonJS code may need to require.
  • Break shared code that two modules both need into a third module, so neither imports the other.
  • Do not set --no-require-module unless you want require() of ES modules to stay off.

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.