mastra-ai/mastra · error

IsolatedVmCodeModeTransport requires the --no-node-snapshot

Error message

IsolatedVmCodeModeTransport requires the --no-node-snapshot flag on Node 20+. Start your process with `node --no-node-snapshot ...` or set NODE_OPTIONS="--no-node-snapshot". Without it, creating a V8 isolate crashes the Node process.

What it means

IsolatedVmCodeModeTransport creates a V8 isolate (via isolated-vm). On Node 20+, if the process was started with the default V8 snapshot, creating an isolate crashes the whole Node process. assertNoNodeSnapshot, called from the transport constructor, throws this error to force you to disable the snapshot with --no-node-snapshot instead of crashing.

Source

Thrown at code-mode/isolated-vm/src/transport.ts:53

export interface IsolatedVmCodeModeTransportOptions {
  /**
   * V8 isolate heap limit in MiB. Exceeding it terminates the program.
   * Default: 128.
   */
  memoryLimitMb?: number;
}

/**
 * On Node 20+, isolated-vm cannot create isolates unless the host process was
 * started with `--no-node-snapshot` — without it, isolate creation crashes the
 * whole process. Detect the documented mechanisms and fail fast instead.
 */
function assertNoNodeSnapshot(): void {
  const major = Number(process.versions.node.split('.')[0]);
  if (major < 20) return;
  if (process.execArgv.includes('--no-node-snapshot')) return;
  if ((process.env.NODE_OPTIONS ?? '').includes('--no-node-snapshot')) return;
  throw new Error(
    'IsolatedVmCodeModeTransport requires the --no-node-snapshot flag on Node 20+. ' +
      'Start your process with `node --no-node-snapshot ...` or set NODE_OPTIONS="--no-node-snapshot". ' +
      'Without it, creating a V8 isolate crashes the Node process.',
  );
}

/** Envelope returned by the guest program eval (as a JSON string). */
interface GuestResultEnvelope {
  ok: boolean;
  value?: unknown;
  error?: { message: string; name?: string };
}

/** Envelope returned by the host RPC handler (as a JSON string). */
interface HostRpcEnvelope {
  ok: boolean;
  result?: unknown;
  error?: { message: string; name?: string };

View on GitHub (pinned to 75dd419e61)

Solutions

1. Start the process with `node --no-node-snapshot ...`
2. Set NODE_OPTIONS="--no-node-snapshot" in your environment/launch script
3. Add the flag to your package.json dev script or Dockerfile ENTRYPOINT/CMD
4. If you cannot change flags, use a different code-mode transport (e.g. local sandbox) that does not need isolates

Example fix

// before
"dev": "mastra dev"
// after
"dev": "NODE_OPTIONS=--no-node-snapshot mastra dev"

const major = Number(process.versions.node.split('.')[0]);
const hasFlag =
  process.execArgv.includes('--no-node-snapshot') ||
  (process.env.NODE_OPTIONS ?? '').includes('--no-node-snapshot');
if (major >= 20 && !hasFlag) {
  throw new Error('Start with --no-node-snapshot before using IsolatedVmCodeModeTransport');
}

function canUseIsolatedVmTransport(): boolean {
  const major = Number(process.versions.node.split('.')[0]);
  return major < 20 || process.execArgv.includes('--no-node-snapshot') || (process.env.NODE_OPTIONS ?? '').includes('--no-node-snapshot');
}

try {
  const transport = new IsolatedVmCodeModeTransport();
} catch (err) {
  if (err instanceof Error && err.message.includes('--no-node-snapshot')) {
    console.error('Relaunch with NODE_OPTIONS="--no-node-snapshot"');
  } else throw err;
}

When it happens

Trigger: Constructing new IsolatedVmCodeModeTransport(...) on Node >= 20 when neither process.execArgv nor NODE_OPTIONS contains --no-node-snapshot.

Common situations: Running a dev server (next dev, mastra dev) without the flag; forgetting that NODE_OPTIONS must carry the flag when execArgv is stripped (workers, containers, test runners); Node 20/22 behavior changes making previously-working setups crash.

Related errors

• NODE_FAIL_INSTALL_SPECIFIED_VERSION
• ${err instanceof Error ? err.message : String(err)}\nYou can
• Code Mode requires a sandbox to run model-authored code, but
• Tool "${toolId}" is not available in Code Mode
• Invalid input for tool "${toolId}"

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/63559428a340cff4. Report an issue: GitHub.