What causes "Failed to load custom "defines": ${error.message}" in vitest-dev/vitest?

Keep all define values JSON-serializable.

vitest-dev/vitest · error · Error

Failed to load custom "defines

Error message

Failed to load custom "defines": ${error.message}

What it means

Same as [367] but on the vm worker path: Vitest runs serializedDefines via runInContext inside the vm context. If the generated JS fails, the inner error is wrapped as 'Failed to load custom "defines": <message>'. Injects config.define values as globals into the vm sandbox before tests run.

Solutions

Keep all define values JSON-serializable.
Inspect the inner error.message (appended after the colon) to find the offending key.
Move runtime values into an imported module rather than define.
Test the serializedDefines string in isolation to reproduce the parse/eval error.

Example fix

// before
define: { __cfg: someClassInstance }

// after
define: { __cfg: JSON.stringify({ mode: 'test' }) }

Defensive patterns

Strategy: validation

Validate before calling

function validateDefines(obj) {
  for (const [k, v] of Object.entries(obj)) {
    try { new Function(`return (${JSON.stringify(v)})`)() } catch {
      throw new Error(`define '${k}' fails to evaluate in a vm context`)
    }
  }
}

Type guard

function isVmSafeDefine(v) {
  try { new Function(`return (${JSON.stringify(v)})`)(); return true } catch { return false }
}

Prevention

Restrict define to JSON-safe primitives and plain objects.
Inspect the inner wrapped message to find the offending key.
Prefer importing runtime values over inlining them in define.

When it happens

Trigger: A define value in vitest.config that is not valid as the body evaluated inside the vm context (functions, circular objects, BigInt, Symbols), or values whose serialized form throws when evaluated. Caught and re-thrown with the inner message.

Common situations: Non-JSON values in define when running the vm pool; a Vite/Vitest plugin injecting non-serializable defines; environment-specific globals that conflict with define names.

Related errors

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/997b3d8774597772. Report an issue: GitHub.

Appendix: source

Thrown at packages/vitest/src/runtime/workers/vm.ts:158

      context,
      externalModulesExecutor,
    },
    configurable: true,
    enumerable: false,
    writable: false,
  })
  context.__vitest_mocker__ = moduleRunner.mocker

  setupEnv(ctx.config.env, state.metaEnv)

  if (ctx.config.serializedDefines) {
    try {
      runInContext(ctx.config.serializedDefines, context, {
        filename: 'virtual:load-defines.js',
      })
    }
    catch (error: any) {
      throw new Error(`Failed to load custom "defines": ${error.message}`)
    }
  }
  await moduleRunner.mocker.initializeSpyModule()

  const { run } = (await moduleRunner.import(
    entryFile,
  )) as typeof import('../runVmTests')

  try {
    await run(
      method,
      ctx.files,
      ctx.config,
      moduleRunner,
      traces,
    )
  }
  finally {

View on GitHub (pinned to 1fa9837ec2)