What causes "Failed to load custom Reporter from ${path}" in vitest-dev/vitest?

Inspect `error.cause` for the real import failure (resolution, syntax, or runtime).

vitest-dev/vitest · error · Error

Failed to load custom Reporter from ${path}

Error message

Failed to load custom Reporter from ${path}

What it means

Thrown by `loadCustomReporterModule` (utils.ts:18) when `runner.import(path)` rejects while loading a custom reporter module. The original error is attached via `Error({ cause })`. This wraps any module-resolution, syntax, or runtime error that occurs when Vitest tries to import the reporter path, preserving the underlying cause for diagnosis.

Source

Thrown at packages/vitest/src/node/reporters/utils.ts:18

import type { ModuleRunner } from 'vite/module-runner'
import type { Vitest } from '../core'
import type { ResolvedConfig } from '../types/config'
import type { Reporter } from '../types/reporter'
import type { BlobReporter } from './blob'
import type { BuiltinReporters, DefaultReporter, DotReporter, GithubActionsReporter, HangingProcessReporter, JsonReporter, JUnitReporter, TapReporter } from './index'
import { ReportersMap } from './index'

async function loadCustomReporterModule<C extends Reporter>(
  path: string,
  runner: ModuleRunner,
): Promise<new (options?: unknown) => C> {
  let customReporterModule: { default: new () => C }
  try {
    customReporterModule = await runner.import(path)
  }
  catch (customReporterModuleError) {
    throw new Error(`Failed to load custom Reporter from ${path}`, {
      cause: customReporterModuleError as Error,
    })
  }

  if (
    customReporterModule.default === null
    || customReporterModule.default === undefined
  ) {
    throw new Error(
      `Custom reporter loaded from ${path} was not the default export`,
    )
  }

  return customReporterModule.default
}

function createReporters(
  reporterReferences: ResolvedConfig['reporters'],

View on GitHub (pinned to d568f8ce37)

Solutions

Inspect `error.cause` for the real import failure (resolution, syntax, or runtime).
Verify the reporter path is correct and the file exists; use a path resolvable by the Vite module runner.
Install any missing dependencies the reporter imports.
Ensure the reporter file has no syntax errors (`node --check` or run it directly).

Example fix

// before
export default defineConfig({ test: { reporters: [['./reporter/mis-typed.ts', {}]] } })
// after: fix path / fix syntax in ./reporter/my-reporter.ts

Defensive patterns

Strategy: try-catch

Validate before calling

import { pathExists } from 'fs-extra'
if (!await pathExists(reporterPath)) throw new Error(`Reporter path does not exist: ${reporterPath}`)

Try / catch

try {
  await import(reporterPath)
} catch (e) {
  throw new Error(`Custom reporter ${reporterPath} failed to load`, { cause: e })
}

Prevention

Verify the reporter path exists and is resolvable before adding it to config.
Keep reporter dependencies installed.
Test the reporter module imports cleanly in isolation first.

When it happens

Trigger: Configuring `reporters: [['./my-reporter.ts', {}]]` where the path doesn't exist, has a syntax error, throws on import, or has an unresolvable dependency; referencing an npm package name that isn't installed.

Common situations: Typo in the reporter path; missing dependency the reporter imports; ESM/CJS mismatch causing import failure; reporter file outside the project root or not on the module resolution path.

Related errors

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