vitest-dev/vitest · critical · Error

Vitest failed to find ${message}. One of the following is po

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

The internal `assert` helper (suite.ts:193-203) guards `getDefaultSuite`, `getCurrentSuite`, and `getRunner`. If the module-level `runner`/`defaultSuite`/`currentSuite` is unset, it means Vitest's runtime was not initialized — these globals are set by `clearCollectorContext` during normal test collection. This typically indicates `vitest` APIs (like `test`, `describe`, `getRunner`) were invoked outside the Vitest execution context.

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 getTestFilepath(): string {
  return currentTestFilepath
}

View on GitHub (pinned to d568f8ce37)

Solutions

Move code that uses `test`/`describe`/Vitest APIs from `globalSetup` into `setupFiles` (which run in the test context).
Do not import `vitest` inside the Vite/Vitest config file.
Ensure you invoke the Vitest CLI (`vitest`/`vitest run`) rather than executing test files directly with `node`.
If this appears during normal runs, report it as a Vitest bug with a reproduction.

Example fix

// before: vitest.config.ts
import { describe, test } from 'vitest' // wrong context
// after: remove test imports from config; put them in test files
// globalSetup: don't use vitest APIs here
default defineConfig({
  test: { globalSetup: ['./setup-db.ts'] }, // setup-db.ts must NOT import vitest test APIs
})

Defensive patterns

Strategy: validation

Validate before calling

// Detect misuse: ensure vitest test APIs are not imported in config or globalSetup.
// In CI, run a check that globalSetup files and vitest.config do not import from 'vitest' test APIs.
// Programmatic check omitted; rely on not importing vitest in those contexts.

Prevention

Never import vitest test APIs (test/describe/expect) in vitest.config.ts or globalSetup files.
Use setupFiles (which run in test context) instead of globalSetup for test-scoped setup.
Always invoke tests via the vitest CLI, not `node`.

When it happens

Trigger: Importing `vitest` (or its internals) and calling `test`/`describe`/`getRunner` in a plain Node script, a `globalSetup` file, or the Vite/Vitest config file itself — anywhere Vitest hasn't run `clearCollectorContext`.

Common situations: Using Vitest globals in `globalSetup` (which runs in a different context); importing `vitest` directly to run tests manually; importing test APIs inside `vitest.config.ts`; SSR/build code accidentally importing test modules.

Related errors

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