vitest-dev/vitest · error · Error

Vitest failed to access its internal state. One of the foll

Error message

Vitest failed to access its internal state.

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 getWorkerState when the global `__vitest_worker__` symbol is missing from globalThis. That symbol is injected by Vitest's runner into each worker/context. When it is absent, it almost always means `vitest` (or code that calls getWorkerState, like expect/vi) is being imported and executed outside of a Vitest worker - e.g. directly by node, inside globalSetup, or inside the config file itself.

Source

Thrown at packages/vitest/src/runtime/utils.ts:21

const NAME_WORKER_STATE = '__vitest_worker__'

export class EnvironmentTeardownError extends Error {
  name = 'EnvironmentTeardownError'
}

export function getWorkerState(): WorkerGlobalState {
  // @ts-expect-error untyped global
  const workerState = globalThis[NAME_WORKER_STATE]
  if (!workerState) {
    const errorMsg
      = 'Vitest failed to access its internal state.'
        + '\n\nOne 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'
    throw new Error(errorMsg)
  }
  return workerState
}

export function getSafeWorkerState(): WorkerGlobalState | undefined {
  // @ts-expect-error untyped global
  return globalThis[NAME_WORKER_STATE]
}

export function provideWorkerState(context: any, state: WorkerGlobalState): WorkerGlobalState {
  Object.defineProperty(context, NAME_WORKER_STATE, {
    value: state,
    configurable: true,
    writable: true,
    enumerable: false,
  })

  return state

View on GitHub (pinned to d568f8ce37)

Solutions

1. Run tests via the `vitest` CLI instead of `node`/`ts-node`.
2. Move code that imports `vitest` out of `globalSetup` into `setupFiles` (globalSetup runs in the main process, not a worker).
3. Do not import `vitest`, `vi`, or `@vitest/expect` inside your vite/vitest config file.
4. If this fires during normal `vitest` runs, it may be a Vitest bug - report it with a reproduction.

Example fix

// before (vitest.config.ts) - throws
import { vi } from 'vitest'
export default defineConfig({ test: { globalSetup: ['./setup.ts'] } })

// after
// vitest.config.ts - do not import vitest here
import { defineConfig } from 'vitest/config'
export default defineConfig({ test: { setupFiles: ['./setup.ts'] } })
// move any `import { ... } from 'vitest'` into ./setup.ts or test files

// Only call vitest APIs when running under Vitest
function assertVitestContext() {
  if (!globalThis.__vitest_worker__) {
    throw new Error('vitest APIs called outside a Vitest worker')
  }
}

function isVitestWorker(): boolean {
  return Boolean((globalThis as any).__vitest_worker__)
}

When it happens

Trigger: Running a file with `node my-test.js` that does `import {describe} from 'vitest'`. Importing `vitest` inside a globalSetup file. Importing `vitest`/`@vitest/expect`/`vi` inside the vitest.config.ts or vite.config.ts. Calling vi.mock or expect in a context Vitest did not initialize.

Common situations: Trying to reuse Vitest's API in a plain Node script. Putting shared helpers that import vitest into globalSetup. Tooling (eslint plugins, typegen) that imports the config file and accidentally evaluates a vitest import.

Related errors

• You've enabled headless mode for "preview" provider but it d
• vitest/browser can be imported only inside the Browser Mode.
• Not called in the browser
• Worker state is not found. This is an issue with Vitest. Ple
• ${name}Browser name is required. Please, set `test.browser.i

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