GoogleChrome/lighthouse · error · Error

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

Error message

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

What it means

Within coerceScreenEmulation, the boolean properties (mobile, disabled) accept the strings 'true'/'false' (manually coerced), actual booleans, or undefined. This error fires when the value is none of those — for instance, the string 'yes', a number, or any other non-boolean/non-coercible value.

Source

Thrown at cli/cli-flags.js:533

      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;
      default:
        throw new Error(`Unrecognized screenEmulation option: ${key}`);
    }
  }

  return screenEmulationSettings;
}

export {
  getFlags,
  getYargsParser,
};

View on GitHub (pinned to 9515cd4e58)

Solutions

1. Use --screenEmulation.mobile or --screenEmulation.disabled as bare flags (sets to true)
2. Use explicit 'true'/'false' strings: --screenEmulation.mobile=true or --screenEmulation.mobile=false
3. Use --no-screenEmulation.mobile for false (if supported by yargs), or --screenEmulation.mobile=false

Example fix

# before
lighthouse --screenEmulation.mobile=yes --screenEmulation.disabled=0 https://example.com
# after
lighthouse --screenEmulation.mobile --screenEmulation.disabled=false https://example.com

const BOOL_EMU_KEYS = ['mobile', 'disabled'];
function validateScreenEmulationBooleans(value) {
  for (const key of BOOL_EMU_KEYS) {
    const v = value[key];
    if (v !== undefined && v !== true && v !== false && v !== 'true' && v !== 'false') {
      throw new Error(`screenEmulation.${key} must be a boolean or 'true'/'false', got ${v}`);
    }
  }
}

When it happens

Trigger: Passing --screenEmulation.mobile or --screenEmulation.disabled with a value that is not true, false, 'true', 'false', or undefined. For example: --screenEmulation.mobile=yes or --screenEmulation.disabled=0.

Common situations: Using 'yes'/'no' or '1'/'0' instead of 'true'/'false'; shell variable expansion producing unexpected values; misunderstanding the accepted boolean string forms.

Related errors

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