{"id":"b58a53863704ddf6","repo":"vitest-dev/vitest","slug":"expected-a-single-value-for-option-command-r","errorCode":null,"errorMessage":"Expected a single value for option \"${command}\", received [${received}]","messagePattern":"Expected a single value for option \"(.+?)\", received \\[(.+?)\\]","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/vitest/src/node/cli/cac.ts","lineNumber":23,"sourceCode":"import cac from 'cac'\nimport { normalize } from 'pathe'\nimport { disableDefaultColors } from 'tinyrainbow'\nimport { version } from '../../../package.json' with { type: 'json' }\nimport { isAgent, isForceColor } from '../../utils/env'\nimport { cliOptionsConfig, collectCliOptionsConfig } from './cli-config'\nimport { setupTabCompletions } from './completions'\n\nfunction addCommand(cli: CAC | Command, name: string, option: CLIOption<any>) {\n  const commandName = option.alias || name\n  let command = option.shorthand ? `-${option.shorthand}, --${commandName}` : `--${commandName}`\n  if ('argument' in option) {\n    command += ` ${option.argument}`\n  }\n\n  function transform(value: unknown) {\n    if (!option.array && Array.isArray(value)) {\n      const received = value.map(s => typeof s === 'string' ? `\"${s}\"` : s).join(', ')\n      throw new Error(\n        `Expected a single value for option \"${command}\", received [${received}]`,\n      )\n    }\n    value = removeQuotes(value)\n    if (option.transform) {\n      return option.transform(value)\n    }\n    if (option.array) {\n      return toArray(value)\n    }\n    if (option.normalize) {\n      return normalize(String(value))\n    }\n    return value\n  }\n\n  const hasSubcommands = 'subcommands' in option && option.subcommands\n","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/vitest/src/node/cli/cac.ts#L5-L41","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass the option only once with the intended value.","If you genuinely need multiple values, switch to the array form the option supports (check `--help`) or use a comma-separated value where supported.","Audit npm scripts and CI matrices for duplicated single-value flags."],"exampleFix":"# before\nvitest --browser=chrome --browser=firefox\n# after\nvitest --browser=chrome","handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pass each single-value CLI option exactly once.","When composing CLI flags from multiple sources, dedupe single-value options.","Use --help to confirm which options accept repeated (array) values."],"tags":[],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}