vitest-dev/vitest · error · Error

vi.when: "${type}" is not a known method

Error message

vi.when: "${type}" is not a known method

What it means

A defensive exhaustiveness guard inside `getMethodName`, which maps each `BehaviorType` (`'return' | 'throw' | 'resolve' | 'reject'`) to its public `then*` method name. The `default` branch is paired with `(type satisfies never)`: under TypeScript this should be unreachable, and at runtime it only fires if an invalid `BehaviorType` somehow reaches the function — indicating an internal Vitest bug or memory corruption of a behavior object.

Source

Thrown at packages/vitest/src/integrations/mock/when.ts:515

function getMethodName(type: BehaviorType): string {
  switch (type) {
    case 'return': {
      return 'thenReturn'
    }
    case 'resolve': {
      return 'thenResolve'
    }
    case 'throw': {
      return 'thenThrow'
    }
    case 'reject': {
      return 'thenReject'
    }
    default: {
      (type satisfies never)

      throw new Error(`vi.when: "${type}" is not a known method`)
    }
  }
}

function hasBeenConsumed(action: BehaviorAction<unknown>): boolean {
  return action.remaining === 0 /* times-actions reached 0 */
    || (action.remaining === Number.POSITIVE_INFINITY && action.called) /* infinite actions called at least once */
}

function getRemainingLabel(action: BehaviorAction<unknown>): string {
  if (hasBeenConsumed(action)) {
    return action.remaining === Number.POSITIVE_INFINITY
      ? 'exhausted'
      : `exhausted (${action.times} of ${action.times})`
  }

  return action.remaining === Number.POSITIVE_INFINITY
    ? 'never called'

View on GitHub (pinned to 1fa9837ec2)

Solutions

1. Report a bug to Vitest with a minimal reproduction — this is not an expected user-facing error.
2. Ensure you are not mutating behavior objects or passing raw objects into Vitest internals.
3. Update to the latest patch of Vitest in case it is a fixed internal regression.

try {
  // normal vi.when usage
} catch (e) {
  if (e instanceof Error && /is not a known method/.test(e.message)) {
    // internal Vitest bug: report upstream with a reproduction
  }
  throw e
}

When it happens

Trigger: Effectively unreachable in normal usage. Could only occur if a behavior object's `type` field was mutated to a non-union string, a third-party plugin injected a behavior with an invalid type, or an internal code path constructed a `BehaviorAction` without going through the public `then*` methods.

Common situations: Should not occur for end users. If seen, suspect a Vitest internal regression, a patched/monkey-patched Vitest, or corrupted module state from HMR.

Related errors

• Assertion name is not set. This is a bug in Vitest. Please,
• stopChunkTrace cannot be called outside of the test file.
• This command can only be called inside a test file.
• provider ${context.provider.name} is not supported
• Browser is not initialized

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