{"record":{"id":"63559428a340cff4","repo":"mastra-ai/mastra","slug":"isolatedvmcodemodetransport-requires-the-no-node","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"code-mode/isolated-vm/src/transport.ts","lineNumber":53,"sourceCode":"export interface IsolatedVmCodeModeTransportOptions {\n  /**\n   * V8 isolate heap limit in MiB. Exceeding it terminates the program.\n   * Default: 128.\n   */\n  memoryLimitMb?: number;\n}\n\n/**\n * On Node 20+, isolated-vm cannot create isolates unless the host process was\n * started with `--no-node-snapshot` — without it, isolate creation crashes the\n * whole process. Detect the documented mechanisms and fail fast instead.\n */\nfunction assertNoNodeSnapshot(): void {\n  const major = Number(process.versions.node.split('.')[0]);\n  if (major < 20) return;\n  if (process.execArgv.includes('--no-node-snapshot')) return;\n  if ((process.env.NODE_OPTIONS ?? '').includes('--no-node-snapshot')) return;\n  throw new Error(\n    'IsolatedVmCodeModeTransport requires the --no-node-snapshot flag on Node 20+. ' +\n      'Start your process with `node --no-node-snapshot ...` or set NODE_OPTIONS=\"--no-node-snapshot\". ' +\n      'Without it, creating a V8 isolate crashes the Node process.',\n  );\n}\n\n/** Envelope returned by the guest program eval (as a JSON string). */\ninterface GuestResultEnvelope {\n  ok: boolean;\n  value?: unknown;\n  error?: { message: string; name?: string };\n}\n\n/** Envelope returned by the host RPC handler (as a JSON string). */\ninterface HostRpcEnvelope {\n  ok: boolean;\n  result?: unknown;\n  error?: { message: string; name?: string };","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/code-mode/isolated-vm/src/transport.ts#L35-L71","documentation":"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.","triggerScenarios":"Constructing new IsolatedVmCodeModeTransport(...) on Node >= 20 when neither process.execArgv nor NODE_OPTIONS contains --no-node-snapshot.","commonSituations":"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.","solutions":["Start the process with `node --no-node-snapshot ...`","Set NODE_OPTIONS=\"--no-node-snapshot\" in your environment/launch script","Add the flag to your package.json dev script or Dockerfile ENTRYPOINT/CMD","If you cannot change flags, use a different code-mode transport (e.g. local sandbox) that does not need isolates"],"exampleFix":"// before\n\"dev\": \"mastra dev\"\n// after\n\"dev\": \"NODE_OPTIONS=--no-node-snapshot mastra dev\"","handlingStrategy":"validation","validationCode":"const major = Number(process.versions.node.split('.')[0]);\nconst hasFlag =\n  process.execArgv.includes('--no-node-snapshot') ||\n  (process.env.NODE_OPTIONS ?? '').includes('--no-node-snapshot');\nif (major >= 20 && !hasFlag) {\n  throw new Error('Start with --no-node-snapshot before using IsolatedVmCodeModeTransport');\n}","typeGuard":"function canUseIsolatedVmTransport(): boolean {\n  const major = Number(process.versions.node.split('.')[0]);\n  return major < 20 || process.execArgv.includes('--no-node-snapshot') || (process.env.NODE_OPTIONS ?? '').includes('--no-node-snapshot');\n}","tryCatchPattern":"try {\n  const transport = new IsolatedVmCodeModeTransport();\n} catch (err) {\n  if (err instanceof Error && err.message.includes('--no-node-snapshot')) {\n    console.error('Relaunch with NODE_OPTIONS=\"--no-node-snapshot\"');\n  } else throw err;\n}","preventionTips":["Always set NODE_OPTIONS=\"--no-node-snapshot\" in dev scripts when using isolated-vm","Add a startup assertion in your entrypoint before constructing the transport","Document the flag requirement for teammates and Docker images","Prefer checking in CI with the same flags as production"],"tags":["node","v8-isolate","startup-flags","code-mode"],"backgroundTag":"node-snapshot-flag-missing","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}