What causes "failed to parse ${options.id}" in vitest-dev/vitest?

Fix any syntax errors in the target module.

vitest-dev/vitest · error · Error

failed to parse ${options.id}

Error message

failed to parse ${options.id}

What it means

Thrown at packages/mocker/src/node/automock.ts:25-33 when the parser (parse callback) throws while transforming a module's source during automocking. The error wraps the underlying parse error with the module id (when options.id is provided) to indicate which file failed to parse, preserving the original cause via Error cause.

Source

Thrown at packages/mocker/src/node/automock.ts:30

  globalThisAccessor?: string
  id?: string
}

// TODO: better source map replacement
export function automockModule(
  code: string,
  mockType: 'automock' | 'autospy',
  parse: (code: string) => any,
  options: AutomockOptions = {},
): MagicString {
  const globalThisAccessor = options.globalThisAccessor || '"__vitest_mocker__"'
  let ast: Program
  try {
    ast = parse(code) as Program
  }
  catch (cause) {
    if (options.id) {
      throw new Error(`failed to parse ${options.id}`, { cause })
    }
    throw cause
  }

  const m = new MagicString(code)

  const allSpecifiers: { name: string; alias?: string }[] = []
  const replacers: (() => void)[] = []
  let importIndex = 0
  for (const _node of ast.body) {
    if (_node.type === 'ExportAllDeclaration') {
      const node = _node as Positioned<ExportAllDeclaration>
      // TODO: pass it down in the browser mode
      if (!options.id) {
        throw new Error(
          `automocking files with \`export *\` is not supported because it cannot be easily statically analysed`,
        )
      }

View on GitHub (pinned to d568f8ce37)

Solutions

Fix any syntax errors in the target module.
Provide an explicit factory to vi.mock so automocking parsing is bypassed: vi.mock('./x', () => ({})).
Ensure the parser/transformer in your Vitest/Vite config supports the syntax (e.g. enable the appropriate TS/JSX/Babel config).

Example fix

// before
vi.mock('./legacy.cjs') // parse fails

// after
vi.mock('./legacy.cjs', () => ({
  doWork: vi.fn(),
}))

Defensive patterns

Strategy: validation

Validate before calling

// Pre-validate the target file is syntactically valid before automocking.
import { readFileSync } from 'node:fs'
import { parse } from 'acorn'
function isParsable(file: string): boolean {
  try { parse(readFileSync(file, 'utf-8'), { ecmaVersion: 'latest', sourceType: 'module' }); return true } catch { return false }
}

if (!isParsable('./target.ts')) {
  // fall back to an explicit factory instead of automock
  vi.mock('./target.ts', () => ({}))
}

Try / catch

try {
  vi.mock('./legacy.cjs')
} catch (e) {
  if (e instanceof Error && /failed to parse/.test(e.message)) {
    // provide an explicit factory to bypass automock parsing
    vi.mock('./legacy.cjs', () => ({}))
  } else { throw e }
}

Prevention

Prefer explicit vi.mock factories for non-standard or legacy file formats.
Keep target modules syntactically valid and supported by your configured parser.
Avoid automocking files with experimental syntax the parser cannot handle.

When it happens

Trigger: vi.mock(path) (automock/auto mode, no factory) targeting a file whose source the configured parser cannot parse: invalid syntax, an unsupported stage-3 proposal, or a file format the parser does not handle.

Common situations: Automocking a TypeScript file with experimental syntax not enabled; a file with a genuine syntax error; a non-JS file being automocked without a transformer; parser version that does not support the syntax in use.

Related errors

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/7efbb2da39bdfb6f.json. Report an issue: GitHub.