{"record":{"id":"bfe026f0253f49eb","repo":"GoogleChrome/lighthouse","slug":"invalid-value-argument-must-be-a-string-or-a-bool","errorCode":null,"errorMessage":"Invalid value: Argument must be a string or a boolean","messagePattern":"Invalid value: Argument must be a string or a boolean","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/cli-flags.js","lineNumber":379,"sourceCode":" * Support comma-separated values for some array flags by splitting on any ',' found.\n * @param {Array<string>=} strings\n * @return {Array<string>=}\n */\nfunction splitCommaSeparatedValues(strings) {\n  if (!strings) return;\n\n  return strings.flatMap(value => value.split(','));\n}\n\n/**\n * @param {unknown} value\n * @return {boolean|string|undefined}\n */\nfunction coerceOptionalStringBoolean(value) {\n  if (value === undefined) return;\n\n  if (typeof value !== 'string' && typeof value !== 'boolean') {\n    throw new Error('Invalid value: Argument must be a string or a boolean');\n  }\n  return value;\n}\n\n/**\n * Coerce output CLI input to `LH.SharedFlagsSettings['output']` or throw if not possible.\n * @param {Array<unknown>} values\n * @return {Array<LH.OutputMode>}\n */\nfunction coerceOutput(values) {\n  const outputTypes = ['json', 'html', 'csv'];\n  const errorHint = `Argument 'output' must be an array from choices \"${outputTypes.join('\", \"')}\"`;\n  if (!values.every(item => typeof item === 'string')) {\n    throw new Error('Invalid values. ' + errorHint);\n  }\n  // Allow parsing of comma-separated values.\n  const strings = values.flatMap(value => value.split(','));\n  const validValues = strings.filter(/** @return {str is LH.OutputMode} */ str => {","sourceCodeStart":361,"sourceCodeEnd":397,"githubUrl":"https://github.com/GoogleChrome/lighthouse/blob/9515cd4e58ebed69f78742d932b501c2cab8ad8f/cli/cli-flags.js#L361-L397","documentation":"Several Lighthouse CLI flags (--emulated-user-agent, --gather-mode/-G, --audit-mode/-A) accept either a string (a path) or a boolean (flag presence). The coerceOptionalStringBoolean function validates this contract. It throws when yargs delivers a value that is neither undefined, a string, nor a boolean — typically a number or an array resulting from unexpected parsing.","triggerScenarios":"Passing a value type that yargs cannot resolve to a string or boolean for --emulated-user-agent, --gather-mode, or --audit-mode. For example, yargs parsing a numeric-looking argument as a number, or an array being passed where the coerce function receives multiple values it cannot reconcile.","commonSituations":"Using --gather-mode=123 where the value looks numeric; complex shell quoting that causes yargs to parse the flag value as a number; programmatic yargs usage passing a non-string/non-boolean; edge cases in yargs array coercion interacting with these flags.","solutions":["Quote the flag value to force string interpretation: --gather-mode=\"./my-artifacts\"","For boolean usage, use the flag with no value: --gather-mode (sets to true) or --no-gather-mode","Ensure the value is a plain string path or omit it for boolean behavior"],"exampleFix":"# before\nlighthouse --gather-mode=12345 https://example.com\n# after\nlighthouse --gather-mode=\"./12345\" https://example.com","handlingStrategy":"validation","validationCode":"// Validate flag value type before passing to Lighthouse CLI\nfunction validateOptionalStringBoolean(value, flagName) {\n  if (value !== undefined && typeof value !== 'string' && typeof value !== 'boolean') {\n    throw new Error(`--${flagName} must be a string or boolean, got ${typeof value}`);\n  }\n}","typeGuard":"/** @param {unknown} v */\nfunction isStringOrBoolean(v) {\n  return typeof v === 'string' || typeof v === 'boolean';\n}","tryCatchPattern":null,"preventionTips":["Always quote string values for --emulated-user-agent, --gather-mode, and --audit-mode","Use bare flags (no value) for boolean behavior: --gather-mode instead of --gather-mode=true","When passing paths, always use quoted strings to avoid numeric interpretation"],"tags":["cli","validation","yargs"],"backgroundTag":null,"analyzedSha":"9515cd4e58ebed69f78742d932b501c2cab8ad8f","analyzedAt":"2026-08-13T06:28:10.346Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}