GoogleChrome/lighthouse · error · Error

Invalid value: Argument 'throttling' must be an object, spec

Error message

Invalid value: Argument 'throttling' must be an object, specified per-property ('throttling.rttMs', 'throttling.throughputKbps', etc)

What it means

The --throttling flag accepts per-property settings as a nested object (e.g., --throttling.rttMs=150). coerceThrottling validates that the aggregated value from yargs is a plain object via isObjectOfUnknownValues. This error fires when the top-level throttling value is not an object at all — for instance, a string, number, or array.

Source

Thrown at cli/cli-flags.js:467

  // (possibly) load and parse extra headers from JSON.
  if (!value.startsWith('{')) {
    // If not a JSON object, assume it's a path to a JSON file.
    return JSON.parse(fs.readFileSync(value, 'utf-8'));
  }
  return JSON.parse(value);
}

/**
 * Take yarg's unchecked object value and ensure it's proper throttling settings.
 * @param {unknown} value
 * @return {LH.ThrottlingSettings|undefined}
 */
function coerceThrottling(value) {
  if (value === undefined) return;

  if (!isObjectOfUnknownValues(value)) {
    throw new Error(`Invalid value: Argument 'throttling' must be an object, specified per-property ('throttling.rttMs', 'throttling.throughputKbps', etc)`);
  }

  /** @type {Array<keyof LH.ThrottlingSettings>} */
  const throttlingKeys = [
    'rttMs',
    'throughputKbps',
    'requestLatencyMs',
    'downloadThroughputKbps',
    'uploadThroughputKbps',
    'cpuSlowdownMultiplier',
  ];

  /** @type {LH.ThrottlingSettings} */
  const throttlingSettings = {};
  for (const key of throttlingKeys) {
    const possibleSetting = value[key];
    if (possibleSetting !== undefined && typeof possibleSetting !== 'number') {
      throw new Error(`Invalid value: 'throttling.${key}' must be a number`);

View on GitHub (pinned to 9515cd4e58)

Solutions

1. Use nested property syntax: --throttling.rttMs=150 --throttling.throughputKbps=1638.40
2. Use a preset instead: --preset=desktop or --preset=perf (which sets throttling automatically)
3. Quote the flag properly if shell is consuming dots: --throttling.cpuSlowdownMultiplier=4

Example fix

# before
lighthouse --throttling=fast https://example.com
# after
lighthouse --throttling.rttMs=150 --throttling.throughputKbps=1638.40 --throttling.cpuSlowdownMultiplier=4 https://example.com

// Validate throttling is an object with numeric properties
function validateThrottling(value) {
  if (value === undefined) return;
  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
    throw new Error('--throttling must be an object; use nested syntax like --throttling.rttMs=150');
  }
}

/** @param {unknown} v */
function isThrottlingObject(v) {
  return typeof v === 'object' && v !== null && !Array.isArray(v);
}

When it happens

Trigger: Passing --throttling as a single non-object value rather than using nested property syntax. For example: --throttling=fast or --throttling=150 instead of --throttling.rttMs=150. Yargs's nested-property coercion produces an object when dot-syntax is used; a bare value produces a non-object.

Common situations: Misunderstanding the throttling flag syntax and passing a bare value instead of nested properties; using a preset name directly; shell quoting that collapses the dot-syntax.

Related errors

• Invalid value: 'throttling.${key}' must be a number
• Invalid precomputed lantern data file
• Please provide a url
• Invalid value: Argument must be a string or a boolean
• Invalid values. Argument 'output' must be an array from choi

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