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

Thrown at packages/mocker/src/node/hoistMocks.ts:53-62 (the API_NOT_FOUND_ERROR string, injected as a runtime check by API_NOT_FOUND_CHECK). When hoistMocks detects vi/vitest usage but the symbols were imported from a module other than the hoisted module (vitest) and globals is disabled, it injects a runtime guard that throws if those names are undefined on globalThis. The message directs you to import the API from 'vitest' or enable globals.

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 d568f8ce37)

Solutions

1. Import the mocking API directly from 'vitest': import { vi } from 'vitest'.
2. Enable the globals option in vitest config (test.globals: true) so vi is available globally.
3. If redistributing Vitest's API under your own specifier, add it to REDISTRIBUTED_HOISTED_MODULES or configure hoistedModule accordingly.

Example fix

// before
import { vi } from './test-utils' // re-exports vi
vi.mock('./logger') // -> API_NOT_FOUND_ERROR

// after
import { vi } from 'vitest'
vi.mock('./logger')

// Ensure vi is imported from 'vitest' (or globals enabled) before relying on it.
function assertMockApiAvailable() {
  // When globals: false and vi is imported from a non-vitest source,
  // the hoisted runtime check will throw. Validate at config time.
  // In vitest.config.ts set test.globals = true, OR always import { vi } from 'vitest'.
}

try {
  vi.mock('./logger')
} catch (e) {
  if (e instanceof Error && /resolving the mocks API/.test(e.message)) {
    console.error('Import vi from "vitest" directly, or enable test.globals in vitest.config.ts')
  }
  throw e
}

When it happens

Trigger: Using vi.* (e.g. vi.mock) after importing vi from a re-exporting package that is not 'vitest' (and not in REDISTRIBUTED_HOISTED_MODULES), with globals: false. The injected check at hoistMocks.ts:575-577 fires because the binding is not the real vitest global.

Common situations: Importing { vi } from a local wrapper module or third-party package instead of 'vitest'; a wrapper that re-exports vi but is not registered as a redistributed hoisted module; misconfigured globals option expecting vi to be a global while it was imported from elsewhere.

Related errors

• ${hoistedNodes.size} call${plural ? 's' : ''} in "${relative

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