GoogleChrome/lighthouse · error · Error

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

Error message

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

What it means

Within coerceScreenEmulation, the numeric properties (width, height, deviceScaleFactor) are validated: if defined, they must be of type number. This error names the specific offending property. It fires when a numeric sub-property receives a non-numeric value.

Source

Thrown at cli/cli-flags.js:518

  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)`);
  }

  /** @type {Array<keyof LH.ScreenEmulationSettings>} */
  const keys = ['width', 'height', 'deviceScaleFactor', 'mobile', 'disabled'];
  /** @type {Partial<LH.ScreenEmulationSettings>} */
  const screenEmulationSettings = {};

  for (const key of keys) {
    const possibleSetting = value[key];
    switch (key) {
      case 'width':
      case 'height':
      case 'deviceScaleFactor':
        if (possibleSetting !== undefined && typeof possibleSetting !== 'number') {
          throw new Error(`Invalid value: 'screenEmulation.${key}' must be a number`);
        }
        screenEmulationSettings[key] = possibleSetting;

        break;
      case 'mobile':
      case 'disabled':
        // Manually coerce 'true'/'false' strings to booleans since nested property types aren't set.
        if (possibleSetting === 'true') {
          screenEmulationSettings[key] = true;
        } else if (possibleSetting === 'false') {
          screenEmulationSettings[key] = false;
        } else if (possibleSetting === undefined || typeof possibleSetting === 'boolean') {
          screenEmulationSettings[key] = possibleSetting;
        } else {
          throw new Error(`Invalid value: 'screenEmulation.${key}' must be a boolean`);
        }

        break;

View on GitHub (pinned to 9515cd4e58)

Solutions

1. Pass bare numeric pixel values without units: --screenEmulation.width=360 (not '360px')
2. Ensure shell variables expand to numbers: WIDTH=360 && lighthouse --screenEmulation.width=$WIDTH
3. Use a preset that sets these values automatically: --preset=mobile

Example fix

# before
lighthouse --screenEmulation.width=360px --screenEmulation.height=640px https://example.com
# after
lighthouse --screenEmulation.width=360 --screenEmulation.height=640 https://example.com

const NUMERIC_EMU_KEYS = ['width', 'height', 'deviceScaleFactor'];
function validateScreenEmulationNumbers(value) {
  for (const key of NUMERIC_EMU_KEYS) {
    const v = value[key];
    if (v !== undefined && typeof v !== 'number') {
      throw new Error(`screenEmulation.${key} must be a number, got ${typeof v}`);
    }
  }
}

When it happens

Trigger: Passing --screenEmulation.width, --screenEmulation.height, or --screenEmulation.deviceScaleFactor with a non-number value. For example: --screenEmulation.width=wide or --screenEmulation.deviceScaleFactor=high.

Common situations: Typing a descriptive word instead of a number; shell variable expansion producing a non-numeric string; quoting that prevents yargs numeric coercion of nested values; using units like '360px' instead of '360'.

Related errors

• Invalid value: Argument 'screenEmulation' must be an object,
• Invalid value: 'screenEmulation.${key}' must be a boolean
• Unrecognized screenEmulation option: ${key}
• Please provide a url
• Invalid value: Argument must be a string or a boolean

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