vitest-dev/vitest · error · TypeError

${name} value must be ${types.join(' or ')}, received "${rec

Error message

${name} value must be ${types.join(' or ')}, received "${receivedType}"

What it means

Thrown by assertTypes() in packages/utils/src/helpers.ts when the typeof a value is not in the allowed list passed by the caller. assertTypes is Vitest's internal runtime guard used across the codebase to validate config values, plugin inputs, and API arguments (e.g. functions, strings, booleans). The message reports the human-readable parameter name, the accepted typeof list, and the received typeof.

Source

Thrown at packages/utils/src/helpers.ts:47

  const stackTrace = err.stack || ''
  Error.prepareStackTrace = prepareStackTrace
  Error.stackTraceLimit = limit
  return stackTrace
}

export function notNullish<T>(v: T | null | undefined): v is NonNullable<T> {
  return v != null
}

export function assertTypes(
  value: unknown,
  name: string,
  types: string[],
): void {
  const receivedType = typeof value
  const pass = types.includes(receivedType)
  if (!pass) {
    throw new TypeError(
      `${name} value must be ${types.join(' or ')}, received "${receivedType}"`,
    )
  }
}

export function isPrimitive(value: unknown): boolean {
  return (
    value === null || (typeof value !== 'function' && typeof value !== 'object')
  )
}

export function slash(path: string): string {
  return path.replace(/\\/g, '/')
}

const postfixRE = /[?#].*$/
export function cleanUrl(url: string): string {
  return url.replace(postfixRE, '')

View on GitHub (pinned to d568f8ce37)

Solutions

1. Read the error message: it states the expected typeof set and the received typeof — coerce or replace the value accordingly.
2. If the call is in your vitest.config, check the documented type of the option and align the value.
3. Add a runtime typeof check before calling the API to fail with a clearer message.
4. For TS users, run pnpm typecheck to catch the mismatch at compile time.

function assertRuntimeType(value: unknown, name: string, types: string[]): void {
  if (!types.includes(typeof value)) {
    throw new TypeError(`${name} value must be ${types.join(' or ')}, received "${typeof value}"`)
  }
}

const isOfType = (value: unknown, types: string[]): boolean =>
  types.includes(typeof value)

When it happens

Trigger: Passing a number where Vitest expects a string or function in a public API (e.g. a reporter name, a setup file, a coverage option); passing undefined where an object is required; type-erased JS callers bypassing TypeScript and feeding wrong-shaped values.

Common situations: Plain-JS projects using Vitest without type checking; config typos; plugin/migration introducing a new required type; calling internal Vitest APIs from userland with the wrong runtime type.

Related errors

• `resolveOptions` has to be used in a test file
• Invalid command name "${name}". Only alphanumeric characters
• Invalid command name "${command}". Only alphanumeric charact
• The browser configuration must have a "browser" property. Th
• The file "${relative(parentConfig.root, file)}" must start w

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