vitest-dev/vitest · error · Error

There are some problems in resolving the mocks API. You may…

Error message

There are some problems in resolving the mocks API.
You may encounter this issue when importing the mocks API from another module other than 'vitest'.
To fix this issue you can either:
- import the mocks API directly from 'vitest'
- enable the 'globals' option

What it means

This is a runtime error injected into transformed test code by `hoistMocks` via `API_NOT_FOUND_CHECK`. After hoisting, `vi.mock`/`vi.hoisted` calls are rewritten to reference `globalThis["vi"]` (or the configured accessor). The injected check verifies those globals exist at runtime; if not, it throws this guidance message. It means the Vitest mocking API (`vi`) was not installed on `globalThis` when the hoisted code executed.

Solutions

Enable `globals: true` in the Vitest config so `vi` is installed on `globalThis`.
Import the mocking API directly from `vitest` (`import { vi } from 'vitest'`) rather than from a re-exporting helper.
If re-exporting is required, add the specifier to the hoister's recognized modules (Vitest recognizes `vite-plus/test` by default; custom forks need corresponding config).
Run the file under `vitest`, not plain Node or another test runner.

Example fix

// before — re-exported import breaks hoisting
// helpers.ts: export { vi } from 'vitest'
import { vi } from './helpers'
vi.mock('./mod')
// after — import directly from vitest
import { vi } from 'vitest'
vi.mock('./mod')

Defensive patterns

Strategy: validation

Validate before calling

// Confirm the mocking API is installed on globalThis before tests run.
if (typeof (globalThis as any).vi === 'undefined') {
  throw new Error('Vitest mocking API not installed. Set globals: true or import vi from "vitest".')
}

Type guard

function isVitestApiInstalled(name: string): boolean {
  return typeof (globalThis as any)[name] !== 'undefined'
}

Prevention

Enable `test.globals: true` in the Vitest config.
Import vi directly from 'vitest', not from a re-exporting helper.
Run transformed test files under the Vitest runtime only.

When it happens

Trigger: Importing `vi`/`vitest` from a module other than `vitest` (so the hoister does not recognize it as the hoisted module), or running transformed test code outside the Vitest runtime that would normally set `globalThis.vi`. Also triggered when `globals: false` and the test imports `vi` from a re-exporting wrapper that the hoister does not whitelist.

Common situations: Re-exporting `vi` from a shared test-helpers module (`export { vi } from 'vitest'`) and importing it back; running Vitest-transformed files under a different runner (plain Node, Jest); `globals: false` combined with an indirect import path; tree-shaking or instrumentation stripping the globalThis setup.

Related errors

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

Appendix: source

Thrown at packages/mocker/src/node/hoistMocks.ts:61

  codeFrameGenerator?: CodeFrameGenerator
  magicString?: () => MagicString
  /**
   * Root of the project
   * @default process.cwd()
   */
  root?: string
  getMap?: () => Rollup.SourceMap
}

const API_NOT_FOUND_ERROR = `There are some problems in resolving the mocks API.
You may encounter this issue when importing the mocks API from another module other than 'vitest'.
To fix this issue you can either:
- import the mocks API directly from 'vitest'
- enable the 'globals' option`

function API_NOT_FOUND_CHECK(names: string[]) {
  return `\nif (${names.map(name => `typeof globalThis["${name}"] === "undefined"`).join(' && ')}) `
    + `{ throw new Error(${JSON.stringify(API_NOT_FOUND_ERROR)}) }\n`
}

function isIdentifier(node: any): node is Positioned<Identifier> {
  return node.type === 'Identifier'
}

function getNodeTail(code: string, node: Node) {
  let end = node.end
  if (code[node.end] === ';') {
    end += 1
  }
  if (code[node.end] === '\n') {
    return end + 1
  }
  if (code[node.end + 1] === '\n') {
    end += 1
  }
  return end

View on GitHub (pinned to 1fa9837ec2)