{"record":{"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/1fa9837ec26533512fdcad8baebf249771bd340a/packages/vitest/src/node/cli/cac.ts#L5-L41","documentation":"Thrown by the CLI option `transform` when an option declared as a single value (no `array: true`) receives more than one value across the command line. Vitest wraps `cac` and rejects multi-value input for scalar options so that ambiguous invocations fail loudly instead of silently keeping only the last value.","triggerScenarios":"Passing the same scalar flag twice (e.g. `--reporter=dot --reporter=json` when `reporter` is not an array option), or an option that expects one argument receiving a comma/space-separated list that `cac` splits into an array. The check is `!option.array && Array.isArray(value)`.","commonSituations":"Copy-pasting CLI flags from a script that already set the option; assuming an option accepts repeats because a sibling option does (`reporters` is `array: true` while `reporter` historically was not); shell expansion turning a glob into multiple args for a scalar flag.","solutions":["Pass the option exactly once: `--name value` instead of `--name a --name b`.","If you genuinely need multiple values, switch to the array form of the option (e.g. `--reporters dot --reporters json`) if one exists.","Inspect the option definition in `cli-config.ts` to confirm whether `array: true` is set; if not, it is scalar by design.","Quote the value if a shell is splitting it: `--filter \"a b\"`."],"exampleFix":"// before\nvitest run --reporter=dot --reporter=json\n\n// after (reporters is the array option)\nvitest run --reporters=dot --reporters=json","handlingStrategy":"validation","validationCode":"// Before invoking parseCLI / cac, dedupe scalar flags.\nfunction dedupeScalarFlags(argv: string[]): string[] {\n  const seen = new Set<string>()\n  const out: string[] = []\n  for (let i = 0; i < argv.length; i++) {\n    const a = argv[i]\n    const m = a.match(/^--([\\w-]+)(?:=(.*))?$/)\n    if (m) {\n      if (seen.has(m[1])) continue // keep first occurrence only\n      seen.add(m[1])\n    }\n    out.push(a)\n  }\n  return out\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Consult the option definition in cli-config.ts to know which flags accept arrays.","Pass multi-value inputs via the documented array form (e.g. `--reporters`). not by repeating a scalar.","Quote shell-expanded values to avoid accidental multi-value splitting."],"tags":["cli","cac","options","argument-parsing"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}