GoogleChrome/lighthouse · error · Error

Invalid value: Argument 'screenEmulation' must be an object,

Error message

Invalid value: Argument 'screenEmulation' must be an object, specified per-property ('screenEmulation.width', 'screenEmulation.deviceScaleFactor', etc)

What it means

The --screenEmulation flag accepts per-property settings as a nested object (width, height, deviceScaleFactor, mobile, disabled). coerceScreenEmulation validates that the aggregated value from yargs is a plain object via isObjectOfUnknownValues. This error fires when the top-level value is not an object — e.g., a bare string or number passed instead of using dot-syntax.

Source

Thrown at cli/cli-flags.js:503

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

  /** @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;

View on GitHub (pinned to 9515cd4e58)

Solutions

1. Use nested property syntax: --screenEmulation.mobile --screenEmulation.width=360 --screenEmulation.height=640
2. Use --preset=mobile or --preset=desktop to set emulation automatically
3. Disable emulation entirely: --screenEmulation.disabled

Example fix

# before
lighthouse --screenEmulation=mobile https://example.com
# after
lighthouse --screenEmulation.mobile --screenEmulation.width=375 --screenEmulation.height=667 https://example.com

function validateScreenEmulation(value) {
  if (value === undefined) return;
  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
    throw new Error('--screenEmulation must be an object; use nested syntax like --screenEmulation.width=360');
  }
}

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

When it happens

Trigger: Passing --screenEmulation as a single non-object value instead of using nested property syntax. For example: --screenEmulation=mobile instead of --screenEmulation.mobile or --screenEmulation.disabled. Yargs produces an object with dot-syntax; a bare value produces a non-object.

Common situations: Misunderstanding the flag syntax; trying to pass a preset name directly; shell quoting consuming the dots; migrating from an older Lighthouse version where the syntax may have differed.

Related errors

• Invalid value: 'screenEmulation.${key}' must be a number
• 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/e6b3dc4c60cc0582. Report an issue: GitHub.