vitest-dev/vitest · error · Error

Vitest failed to find

Error message

Vitest failed to find ${message}. One of the following is possible:
- "vitest" is imported directly without running "vitest" command
- "vitest" is imported inside "globalSetup" (to fix this, use "setupFiles" instead, because "globalSetup" runs in a different context)
- "vitest" is imported inside Vite / Vitest config file
- Otherwise, it might be a Vitest bug. Please report it to https://github.com/vitest-dev/vitest/issues

What it means

Thrown by the internal assert() helper when one of the module-level singletons (defaultSuite, runner, currentTestFilepath) is accessed before the Vitest runtime initialized them. The Vitest API (describe/test/expect) only works inside files executed by the Vitest runner process; importing these APIs in other contexts leaves the singletons unset.

Solutions

Move setup code that uses vitest APIs from globalSetup into setupFiles.
Do not import 'vitest' from config files; use plain Node APIs there.
Run tests via the vitest CLI (`vitest`, `vitest run`) rather than node/ts-node.
If the file is not a test, do not import vitest's test APIs at all.

Example fix

// before: vitest.config.ts
import { describe } from 'vitest' // throws at load

// after: vitest.config.ts
import { defineConfig } from 'vitest/config'
export default defineConfig({ test: { setupFiles: ['./setup.ts'] } })

// setup.ts
import { expect } from 'vitest' // ok: runs in test context

Defensive patterns

Strategy: validation

Validate before calling

// Ensure vitest APIs are only imported in files run by the vitest CLI.
// In config files and globalSetup, use plain Node APIs.

Prevention

Do not import vitest from vitest.config.ts or vite.config.ts.
Use setupFiles (not globalSetup) for code that needs vitest APIs.
Always run tests via the vitest CLI, never `node test.ts`.
Keep vitest imports out of library source that ships to non-test bundles.

When it happens

Trigger: Importing 'vitest' (or its named exports test/describe/expect) from globalSetup, from the Vitest/Vite config file, from a plain Node script, or from a different process. Each of the four message variants points to one of these.

Common situations: Using test utilities inside globalSetup (which runs in a separate context); importing vitest in vitest.config.ts; running a test file directly with `node file.test.ts` instead of via the vitest CLI; importing vitest inside a Vite plugin.

Related errors

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

Appendix: source

Thrown at packages/vitest/src/runtime/runner/suite.ts:195

 * });
 * ```
 * @example
 * ```ts
 * // Define a test with options
 * it('subtracts two numbers', { retry: 3 }, () => {
 *   expect(subtract(5, 2)).toBe(3);
 * });
 * ```
 */
export const it: TestAPI = test

let runner: VitestRunner
let defaultSuite: SuiteCollector
let currentTestFilepath: string

function assert(condition: any, message: string) {
  if (!condition) {
    throw new Error(
      `Vitest failed to find ${message}. One of the following is possible:`
      + '\n- "vitest" is imported directly without running "vitest" command'
      + '\n- "vitest" is imported inside "globalSetup" (to fix this, use "setupFiles" instead, because "globalSetup" runs in a different context)'
      + '\n- "vitest" is imported inside Vite / Vitest config file'
      + '\n- Otherwise, it might be a Vitest bug. Please report it to https://github.com/vitest-dev/vitest/issues\n',
    )
  }
}

export function getDefaultSuite(): SuiteCollector<object> {
  assert(defaultSuite, 'the default suite')
  return defaultSuite
}

export function getRunner(): VitestRunner {
  assert(runner, 'the runner')
  return runner
}

View on GitHub (pinned to 1fa9837ec2)