vitest-dev/vitest · error · TypeError

vi.hoisted() expects a function, but received a ${typeof fac

Error message

vi.hoisted() expects a function, but received a ${typeof factory}

What it means

Thrown at packages/mocker/src/browser/hints.ts:54-58 as a TypeError when vi.hoisted() is called with a non-function argument. vi.hoisted must receive a factory function because it executes it immediately at hoist time and returns the factory's return value, which is impossible without a callable.

Source

Thrown at packages/mocker/src/browser/hints.ts:55

      // @ts-expect-error injected by the plugin
      ? globalThis[globalThisAccessor]
      : new Proxy(
          {} as any,
          {
            get(_, name) {
              throw new Error(
                'Vitest mocker was not initialized in this environment. '
                + `vi.${String(name)}() is forbidden.`,
              )
            },
          },
        )
  }

  return {
    hoisted<T>(factory: () => T): T {
      if (typeof factory !== 'function') {
        throw new TypeError(
          `vi.hoisted() expects a function, but received a ${typeof factory}`,
        )
      }
      return factory()
    },

    mock(path: string | Promise<unknown>, factory?: ModuleMockOptions | ModuleMockFactoryWithHelper): void {
      if (typeof path !== 'string') {
        throw new TypeError(
          `vi.mock() expects a string path, but received a ${typeof path}`,
        )
      }
      const importer = getImporter('mock')
      _mocker().queueMock(
        path,
        importer,
        typeof factory === 'function'
          ? () =>

View on GitHub (pinned to d568f8ce37)

Solutions

Pass a function to vi.hoisted: vi.hoisted(() => ({ mock: true })).
If you intended to share a value, wrap it in a factory that returns it.

Example fix

// before
const data = vi.hoisted({ count: 0 })

// after
const data = vi.hoisted(() => ({ count: 0 }))

Defensive patterns

Strategy: type-guard

Validate before calling

// Validate the factory is a function before calling vi.hoisted.
function hoisted<T>(factory: () => T): T {
  if (typeof factory !== 'function') {
    throw new TypeError(`vi.hoisted() requires a function, got ${typeof factory}`)
  }
  return vi.hoisted(factory)
}

Type guard

function isHoistFactory<T>(value: unknown): value is () => T {
  return typeof value === 'function'
}

Prevention

Always pass an arrow function: vi.hoisted(() => value).
Enable strict TypeScript so non-function arguments are caught at compile time.
Avoid reusing vi.mock's string-argument muscle memory with vi.hoisted.

When it happens

Trigger: Calling vi.hoisted(undefined), vi.hoisted(null), vi.hoisted('value'), vi.hoisted({}), or vi.hoisted(someVariable) where the variable is not a function.

Common situations: Passing a value instead of a factory: vi.hoisted({ mock: true }); passing a variable that was conditionally assigned and is undefined in some path; copy-paste from vi.mock which takes a string.

Related errors

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