GoogleChrome/lighthouse · error · Error

Invalid value: Argument must be a string or a boolean

Error message

Invalid value: Argument must be a string or a boolean

What it means

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.

Source

Thrown at cli/cli-flags.js:379

 * Support comma-separated values for some array flags by splitting on any ',' found.
 * @param {Array<string>=} strings
 * @return {Array<string>=}
 */
function splitCommaSeparatedValues(strings) {
  if (!strings) return;

  return strings.flatMap(value => value.split(','));
}

/**
 * @param {unknown} value
 * @return {boolean|string|undefined}
 */
function coerceOptionalStringBoolean(value) {
  if (value === undefined) return;

  if (typeof value !== 'string' && typeof value !== 'boolean') {
    throw new Error('Invalid value: Argument must be a string or a boolean');
  }
  return value;
}

/**
 * Coerce output CLI input to `LH.SharedFlagsSettings['output']` or throw if not possible.
 * @param {Array<unknown>} values
 * @return {Array<LH.OutputMode>}
 */
function coerceOutput(values) {
  const outputTypes = ['json', 'html', 'csv'];
  const errorHint = `Argument 'output' must be an array from choices "${outputTypes.join('", "')}"`;
  if (!values.every(item => typeof item === 'string')) {
    throw new Error('Invalid values. ' + errorHint);
  }
  // Allow parsing of comma-separated values.
  const strings = values.flatMap(value => value.split(','));
  const validValues = strings.filter(/** @return {str is LH.OutputMode} */ str => {

View on GitHub (pinned to 9515cd4e58)

Solutions

1. Quote the flag value to force string interpretation: --gather-mode="./my-artifacts"
2. For boolean usage, use the flag with no value: --gather-mode (sets to true) or --no-gather-mode
3. Ensure the value is a plain string path or omit it for boolean behavior

Example fix

# before
lighthouse --gather-mode=12345 https://example.com
# after
lighthouse --gather-mode="./12345" https://example.com

// Validate flag value type before passing to Lighthouse CLI
function validateOptionalStringBoolean(value, flagName) {
  if (value !== undefined && typeof value !== 'string' && typeof value !== 'boolean') {
    throw new Error(`--${flagName} must be a string or boolean, got ${typeof value}`);
  }
}

/** @param {unknown} v */
function isStringOrBoolean(v) {
  return typeof v === 'string' || typeof v === 'boolean';
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Please provide a url
• Invalid values. Argument 'output' must be an array from choi
• "${str}" is not a valid 'output' value. Argument 'output' mu
• --output-path (${value}) cannot be written to
• Invalid value: Argument 'locale' must be a string

AI-assisted analysis of GoogleChrome/lighthouse@9515cd4e58 (2026-08-13). Data as JSON: /api/errors/bfe026f0253f49eb. Report an issue: GitHub.