vitest-dev/vitest · error · Error

Expected a single value for option "${command}", received [$

Error message

Expected a single value for option "${command}", received [${received}]

What it means

Thrown during CLI option parsing by the cac `transform` helper when a non-array option receives multiple values (an array). Each option in cli-config declares whether it is an array (`array: true`); for single-value options, cac accumulates repeated occurrences into an array, and the transform rejects that array because the option expects exactly one value.

Source

Thrown at packages/vitest/src/node/cli/cac.ts:23

import cac from 'cac'
import { normalize } from 'pathe'
import { disableDefaultColors } from 'tinyrainbow'
import { version } from '../../../package.json' with { type: 'json' }
import { isAgent, isForceColor } from '../../utils/env'
import { cliOptionsConfig, collectCliOptionsConfig } from './cli-config'
import { setupTabCompletions } from './completions'

function addCommand(cli: CAC | Command, name: string, option: CLIOption<any>) {
  const commandName = option.alias || name
  let command = option.shorthand ? `-${option.shorthand}, --${commandName}` : `--${commandName}`
  if ('argument' in option) {
    command += ` ${option.argument}`
  }

  function transform(value: unknown) {
    if (!option.array && Array.isArray(value)) {
      const received = value.map(s => typeof s === 'string' ? `"${s}"` : s).join(', ')
      throw new Error(
        `Expected a single value for option "${command}", received [${received}]`,
      )
    }
    value = removeQuotes(value)
    if (option.transform) {
      return option.transform(value)
    }
    if (option.array) {
      return toArray(value)
    }
    if (option.normalize) {
      return normalize(String(value))
    }
    return value
  }

  const hasSubcommands = 'subcommands' in option && option.subcommands

View on GitHub (pinned to d568f8ce37)

Solutions

1. Pass the option only once with the intended value.
2. If you genuinely need multiple values, switch to the array form the option supports (check `--help`) or use a comma-separated value where supported.
3. Audit npm scripts and CI matrices for duplicated single-value flags.

Example fix

# before
vitest --browser=chrome --browser=firefox
# after
vitest --browser=chrome

When it happens

Trigger: Passing the same single-value CLI flag more than once, e.g. `--browser=chrome --browser=firefox` when `browser` is not declared with `array: true`, or `--root=./a --root=./b`. The transform sees `Array.isArray(value)` true on a non-array option and throws.

Common situations: Combining CLI flags from multiple sources (npm scripts + env + manual) that repeat a single-value option; shell scripts that append flags conditionally and end up duplicating one; misunderstanding which options accept repeated values.

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