GoogleChrome/lighthouse · error · Error

Invalid value: 'throttling.${key}' must be a number

Error message

Invalid value: 'throttling.${key}' must be a number

What it means

After confirming --throttling is an object, coerceThrottling iterates over the six recognized keys (rttMs, throughputKbps, requestLatencyMs, downloadThroughputKbps, uploadThroughputKbps, cpuSlowdownMultiplier). For each key that is present (not undefined), it requires a number type. This error names the specific offending property.

Source

Thrown at cli/cli-flags.js:485

    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`);
    }
    // Note: this works type-wise because the throttling settings all have the same type.
    throttlingSettings[key] = possibleSetting;
  }

  return throttlingSettings;
}

/**
 * Take yarg's unchecked object value and ensure it is a proper LH.screenEmulationSettings.
 * @param {unknown} value
 * @return {Partial<LH.ScreenEmulationSettings>|undefined}
 */
function coerceScreenEmulation(value) {
  if (value === undefined) return;

  if (!isObjectOfUnknownValues(value)) {
    throw new Error(`Invalid value: Argument 'screenEmulation' must be an object, specified per-property ('screenEmulation.width', 'screenEmulation.deviceScaleFactor', etc)`);

View on GitHub (pinned to 9515cd4e58)

Solutions

1. Pass bare numeric values without units: --throttling.rttMs=150 (not '150ms')
2. Ensure shell variables expand to numbers: THROTTLE_RTT=150 && lighthouse --throttling.rttMs=$THROTTLE_RTT
3. Use a preset to avoid manual throttling values: --preset=mobile or --preset=desktop

Example fix

# before
lighthouse --throttling.rttMs=150ms --throttling.cpuSlowdownMultiplier=high https://example.com
# after
lighthouse --throttling.rttMs=150 --throttling.cpuSlowdownMultiplier=4 https://example.com

const NUMERIC_THROTTLING_KEYS = ['rttMs','throughputKbps','requestLatencyMs','downloadThroughputKbps','uploadThroughputKbps','cpuSlowdownMultiplier'];
function validateThrottlingValues(value) {
  for (const key of NUMERIC_THROTTLING_KEYS) {
    const v = value[key];
    if (v !== undefined && typeof v !== 'number') {
      throw new Error(`throttling.${key} must be a number, got ${typeof v}`);
    }
  }
}

When it happens

Trigger: Passing a recognized throttling sub-property with a non-number value. For example: --throttling.rttMs=fast or --throttling.cpuSlowdownMultiplier=high where the value resolves to a string rather than a numeric value.

Common situations: Typing a descriptive word instead of a number; shell variable expansion producing a non-numeric string; yargs not coercing the nested value to a number due to quoting; using units like '150ms' instead of bare '150'.

Related errors

• Invalid value: Argument 'throttling' must be an object, spec
• 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/866d9491f78be65d. Report an issue: GitHub.