What causes "importActual is not implemented" in vitest-dev/vitest?

Run the affected test in the Node environment (`// @vitest-environment node`) where `NativeModuleMocker` is used.

vitest-dev/vitest · error · Error

importActual is not implemented

Error message

importActual is not implemented

What it means

`BareModuleMocker` is the abstract base: it handles mock registration/resolution but does NOT implement actual module loading. Its `importActual` (`bareModuleMocker.ts:288`) unconditionally throws `"importActual is not implemented"`. Only the `NativeModuleMocker` subclass (which drives Node's native ESM loader) provides a real `importActual`. Hitting this means the active mocker isn't the native one.

Source

Thrown at packages/vitest/src/runtime/moduleRunner/bareModuleMocker.ts:288

    else if (mockType === 'autospy') {
      registry.register('autospy', originalId, id, url)
    }
    else {
      const redirect = this.findMockRedirect(id, external)
      if (redirect) {
        registry.register('redirect', originalId, id, url, redirect)
      }
      else {
        registry.register('automock', originalId, id, url)
      }
    }

    // every time the mock is registered, we remove the previous one from the cache
    this.invalidateModuleById(id)
  }

  async importActual<T>(_rawId: string, _importer: string, _callstack?: string[] | null): Promise<T> {
    throw new Error(`importActual is not implemented`)
  }

  async importMock<T>(_rawId: string, _importer: string, _callstack?: string[] | null): Promise<T> {
    throw new Error(`importMock is not implemented`)
  }

  public queueMock(
    id: string,
    importer: string,
    factoryOrOptions?: MockFactory | MockOptions,
  ): void {
    const mockType = getMockType(factoryOrOptions)
    BareModuleMocker.pendingIds.push({
      action: 'mock',
      id,
      importer,
      factory: typeof factoryOrOptions === 'function' ? factoryOrOptions : undefined,
      type: mockType,

View on GitHub (pinned to d568f8ce37)

Solutions

Run the affected test in the Node environment (`// @vitest-environment node`) where `NativeModuleMocker` is used.
Avoid `vi.importActual` in browser tests; restructure mocks so the real module isn't needed.
Use a manual factory (`vi.mock('mod', () => realish)` ) that doesn't require loading the actual module.

Defensive patterns

Strategy: validation

Validate before calling

// Detect whether the native mocker is available before relying on importActual.
// In browser/worker pools the bare mocker is used and importActual throws.
const isNode = typeof process !== 'undefined' && process.versions?.node
if (!isNode) {
  throw new Error('vi.importActual is unavailable in this environment')
}
const actual = await vi.importActual('mod')

Try / catch

try {
  return await vi.importActual('mod')
} catch (e) {
  if (e instanceof Error && /importActual is not implemented/.test(e.message)) {
    // provide a manual factory instead, or move test to node env
  }
  throw e
}

Prevention

Run tests that use vi.importActual in the Node environment (@vitest-environment node).
Avoid vi.importActual in browser tests.
Prefer vi.mock with an explicit factory that doesn't need the real module.

When it happens

Trigger: Calling `vi.importActual('mod')` in an environment wired with `BareModuleMocker` — typically the browser pool or a runtime without the native loader hook.

Common situations: Running mocking tests in the browser (Playwright/WebDriverIO) where native import isn't available; a workspace/child process using the bare mocker; misconfigured environment.

Related errors

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