Jest tests crash on import() with a message about --experimental-vm-modules
TypeError: A dynamic import callback was invoked without --experimental-vm-modulesShort 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.
Fix it fast
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.js2Match what you see, then jump to its fix
- 1
The 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
The 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
The 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
- 1
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.json2Fix
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 jest3Verify
Run the single failing test file and confirm the dynamic import error is gone.
npm test -- path/to/failing.test.jsConfirmed by jestjs.io
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_OPTIONS2Fix
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 testConfirmed by jestjs.io
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" src2Fix
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.jsConfirmed by jestjs.io
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 fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Can't resolve '../axios' in a React project
Module not found: Error: Can't resolve '../axios'
A path that starts with ./ or ../ is a file path, not the axios package.
3 causes, each with a fix