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

Inspect the `cause` on the thrown error for the underlying parse error and line number.

vitest-dev/vitest · error · Error

failed to parse

Error message

failed to parse ${options.id}

What it means

Thrown by `automockModule` when the provided `parse` function fails to parse the module source and `options.id` is set. The original parse error is attached as `cause`. Automocking transforms a module's source into a mocked version, so it must parse the AST first; a parse failure means the source contains syntax the configured parser (typically acorn) rejects.

Solutions

Inspect the `cause` on the thrown error for the underlying parse error and line number.
Fix the syntax error in the target module if one exists.
Provide an explicit factory to `vi.mock(path, factory)` to bypass automock parsing entirely.
If the syntax is valid modern JS, update Vitest — newer versions bundle newer parsers.

Example fix

// before — automock fails to parse the module
vi.mock('./broken-mod')
// after — provide a factory to skip parsing
vi.mock('./broken-mod', () => ({ fn: vi.fn() }))

Defensive patterns

Strategy: fallback

Validate before calling

// Detect unparseable source before automock by attempting a parse in a scratch build step, or simply prefer explicit factories for modules known to use unsupported syntax.

Try / catch

try {
  vi.mock('./mod') // automock path
} catch (err) {
  if (err instanceof Error && err.message.startsWith('failed to parse')) {
    vi.mock('./mod', () => ({ /* explicit stubs */ }))
  }
}

Prevention

Provide an explicit factory for modules using leading-edge or non-standard syntax.
Keep Vitest updated so the bundled parser supports newer ECMAScript features.
Read err.cause for the exact parse failure and line number before changing code.

When it happens

Trigger: `vi.mock(path)` (without a factory) is called against a module whose source cannot be parsed by the automock pipeline — e.g., it uses newer ECMAScript syntax than the parser supports, contains a genuine syntax error, or uses TypeScript decorators/JSX that the plain acorn parser does not understand (note: TS type-stripping is handled separately by `transformCode`).

Common situations: Automocking a module that uses stage-3/4 syntax not yet supported by the bundled acorn; a source file with an actual syntax error that Vite tolerates via a different parser; automocking a `.tsx`/`.jsx` file whose JSX is not pre-stripped before reaching the automock parser.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: 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 1fa9837ec2)