Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Jest tests crash on import() with a message about --experimental-vm-modules

ErrorTypeError: A dynamic import callback was invoked without --experimental-vm-modules

Short answer

Jest runs test files inside Node's vm module. A dynamic import() or native ESM file in that sandbox only works when Node starts with --experimental-vm-modules. Start Jest through node with the flag, or set it in NODE_OPTIONS. If you cannot use ESM, make your transformer emit CommonJS instead.

  • Applies to Jest 29, Jest 30, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find the exact command that starts Jest (npm script, CI step or IDE runner) and see whether Node receives the flag. Run it by hand with the flag from the Jest docs and watch whether the error disappears.

    grep -n "jest" package.json
    node --experimental-vm-modules node_modules/jest/bin/jest.js
  2. 2Match what you see, then jump to its fix

    1. 1The error appears on the first test that reaches an import() call or an ES module, and the command is plain jestJest is started without the Node flagFix
    2. 2The script works on macOS or Linux but the same npm script fails on Windows or in a CI jobThe variable is set in a way the shell or CI does not understandFix
    3. 3The error shows only in a test that mocks a module and then awaits import()A mock loads the module with import() but ESM mocking is not set upFix

What does the error look like?

  • TypeError: A dynamic import callback was invoked without --experimental-vm-modules

Cause 1 of 3

Jest is started without the Node flag

1Check

Look at the npm script. If it only says jest, Node starts without the flag. Jest follows Node's rules for ESM mode: a type field in package.json, .mjs files, or extensionsToTreatAsEsm.

grep -n '"type"' package.json
grep -n -E "extensionsToTreatAsEsm|transform" jest.config.* package.json

2Fix

Run Jest through node with the flag, or put the flag into NODE_OPTIONS for the script. If you use ESM mode, the Jest docs also say to turn transforms off with transform: {} or to configure your transformer to emit ESM.

# package.json scripts
"test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"

# or, in a POSIX shell
NODE_OPTIONS="$NODE_OPTIONS --experimental-vm-modules" npx jest

3Verify

Run the single failing test file and confirm the dynamic import error is gone.

npm test -- path/to/failing.test.js

Confirmed by jestjs.io

Did this fix it?

Cause 2 of 3

The variable is set in a way the shell or CI does not understand

1Check

Inline VAR=value NODE_OPTIONS syntax is POSIX only. On Windows cmd or PowerShell it is ignored or errors, so Node starts without the flag.

echo $NODE_OPTIONS

2Fix

The Jest docs point to cross-env for setting environment variables on Windows. Install it as a dev dependency and use it in the script.

npm install --save-dev cross-env

# package.json scripts
"test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest"

3Verify

Run the npm script on the failing machine or runner.

npm test

Confirmed by jestjs.io

Did this fix it?

Cause 3 of 3

A mock loads the module with import() but ESM mocking is not set up

1Check

In ESM mode static imports run before any code, so jest.mock hoisting does not apply. Look for jest.mock calls next to await import() in the failing test.

grep -rn -E "jest\.(mock|unstable_mockModule)|await import" src

2Fix

Call jest.unstable_mockModule first, then load the module under test with await import(). Modules that depend on the mocked module must be loaded the same way. This runs with the flag from the first cause.

import {jest} from '@jest/globals';

jest.unstable_mockModule('node:child_process', () => ({
  execSync: jest.fn(),
}));

const {execSync} = await import('node:child_process');

3Verify

Run the test with the flag; the mock should be called and no vm-modules error should appear.

node --experimental-vm-modules node_modules/jest/bin/jest.js path/to/failing.test.js

Confirmed by jestjs.io

Did this fix it?

How do I stop it coming back?

  • Keep the flag inside the npm script, so CI, IDE and teammates all start Jest the same way.
  • Run the test suite on a branch before merging a big dependency upgrade.
  • Pick one module style per package: either CommonJS with a Babel transform, or ESM with the flag.

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

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 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.