Node.js "vm.Module not available" - Fix Missing --experimental-vm-modules

Node’s vm.SourceTextModule / vm.Module ESM API is experimental and only exists when Node is started with --experimental-vm-modules. Tools and tests that evaluate ES modules in a VM context (some custom loaders, coverage, and ESM-aware test setups) need that flag set.

What this error means

A run fails with vm.Module is not available or a message that the process must be run with --experimental-vm-modules. The same code works once the flag is passed via the command line or NODE_OPTIONS.

Error: vm.Module is not available, you must run Node.js with the
--experimental-vm-modules flag
    at new SourceTextModule (node:vm)
    at ...

Common causes

The experimental VM-modules flag was not set

The VM ESM API is behind --experimental-vm-modules. Without it, constructing a vm.SourceTextModule throws because the API is not present.

A tool that evaluates ESM in a VM context

A custom loader, an ESM-aware coverage tool, or a test setup that compiles modules in a VM relies on the flag; running it without the flag fails.

How to fix it

Pass the flag to Node

Enable the experimental VM modules API when invoking the tool.

# via NODE_OPTIONS (this flag is allowed there)
NODE_OPTIONS=--experimental-vm-modules npx <tool>

# or directly
node --experimental-vm-modules ./node_modules/.bin/<tool>

Confirm the tool genuinely needs it

1. Check the tool’s docs - many ESM-aware runners document this requirement.
2. Set the flag once in the package.json test/build script so CI inherits it.
3. Keep the flag scoped to the step that needs it rather than globally.

How to prevent it

• Set --experimental-vm-modules in the script that needs the VM ESM API.
• Document why the flag is required for the step.
• Track when the API leaves experimental status so the flag can drop.

Related guides