vitest-dev/vitest · error · Error

[vitest] "registerHooks" is not available when running in Vi

Error message

[vitest] "registerHooks" is not available when running in Vitest.

What it means

Thrown by Vitest's custom `Module` shim when user code calls `module.registerHooks(...)` (Node's runtime hooks registration, added in newer Node versions). Like register, this is intentionally disabled in the sandboxed vm CommonJS executor because runtime hooks cannot be applied to modules compiled and evaluated inside the Vitest vm context.

Source

Thrown at packages/vitest/src/runtime/vm/commonjs-executor.ts:109

      static getSourceMapsSupport = () => ({
        enabled: false,
        nodeModules: false,
        generatedCode: false,
      })

      static setSourceMapsSupport = () => {
        // noop
      }

      static register = () => {
        throw new Error(
          `[vitest] "register" is not available when running in Vitest.`,
        )
      }

      static registerHooks = () => {
        throw new Error(
          `[vitest] "registerHooks" is not available when running in Vitest.`,
        )
      }

      _compile(code: string, filename: string) {
        const cjsModule = Module.wrap(code)
        const codeCache = executor.codeCache
        const cachedData = codeCache?.get(filename, cjsModule)
        const script = new vm.Script(cjsModule, {
          filename,
          cachedData,
          importModuleDynamically: options.importModuleDynamically,
        } as any)
        if (cachedData && script.cachedDataRejected) {
          codeCache!.delete(filename)
        }
        // @ts-expect-error mark script with current identifier
        script.identifier = filename

View on GitHub (pinned to d568f8ce37)

Solutions

Remove the `Module.registerHooks(...)` call from code exercised in tests.
Stub the dependency that calls registerHooks via vi.mock, or exclude it from the test bundle.
Gate the call behind an environment check (e.g. only when not running under Vitest).
Avoid Node runtime-hook APIs in code that Vitest loads.

Example fix

// before
const Module = require('module')
Module.registerHooks({ evaluateLoaders() { /* ... */ } })

// after
const Module = require('module')
if (!process.env.VITEST) {
  Module.registerHooks({ evaluateLoaders() { /* ... */ } })
}

Defensive patterns

Strategy: validation

Validate before calling

const shouldRegisterHooks = !process.env.VITEST && !globalThis.__vitest_worker__
if (shouldRegisterHooks) {
  require('module').registerHooks({ /* ... */ })
}

Prevention

Avoid Node runtime-hook APIs in test-loaded code.
Gate registerHooks behind a non-Vitest env check.
Stub libraries that auto-register hooks via vi.mock.

When it happens

Trigger: Test code or a transitive dependency calls `require('module').registerHooks(...)` (or `Module.registerHooks`) while executing under Vitest's vm-based CommonJS executor. Some instrumentation/tracing/profiling libraries call registerHooks automatically.

Common situations: Using a profiling or tracing library that auto-registers Node runtime hooks. Copying initialization code from a server bootstrap into a test. Newer Node-version-specific code paths that hit registerHooks.

Related errors

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