{"record":{"id":"3157c0b24134793c","repo":"GoogleChrome/lighthouse","slug":"invalid-value-screenemulation-key-must-be-a","errorCode":null,"errorMessage":"Invalid value: 'screenEmulation.${key}' must be a number","messagePattern":"Invalid value: 'screenEmulation\\.(.+?)' must be a number","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/cli-flags.js","lineNumber":518,"sourceCode":"  if (value === undefined) return;\n\n  if (!isObjectOfUnknownValues(value)) {\n    throw new Error(`Invalid value: Argument 'screenEmulation' must be an object, specified per-property ('screenEmulation.width', 'screenEmulation.deviceScaleFactor', etc)`);\n  }\n\n  /** @type {Array<keyof LH.ScreenEmulationSettings>} */\n  const keys = ['width', 'height', 'deviceScaleFactor', 'mobile', 'disabled'];\n  /** @type {Partial<LH.ScreenEmulationSettings>} */\n  const screenEmulationSettings = {};\n\n  for (const key of keys) {\n    const possibleSetting = value[key];\n    switch (key) {\n      case 'width':\n      case 'height':\n      case 'deviceScaleFactor':\n        if (possibleSetting !== undefined && typeof possibleSetting !== 'number') {\n          throw new Error(`Invalid value: 'screenEmulation.${key}' must be a number`);\n        }\n        screenEmulationSettings[key] = possibleSetting;\n\n        break;\n      case 'mobile':\n      case 'disabled':\n        // Manually coerce 'true'/'false' strings to booleans since nested property types aren't set.\n        if (possibleSetting === 'true') {\n          screenEmulationSettings[key] = true;\n        } else if (possibleSetting === 'false') {\n          screenEmulationSettings[key] = false;\n        } else if (possibleSetting === undefined || typeof possibleSetting === 'boolean') {\n          screenEmulationSettings[key] = possibleSetting;\n        } else {\n          throw new Error(`Invalid value: 'screenEmulation.${key}' must be a boolean`);\n        }\n\n        break;","sourceCodeStart":500,"sourceCodeEnd":536,"githubUrl":"https://github.com/GoogleChrome/lighthouse/blob/9515cd4e58ebed69f78742d932b501c2cab8ad8f/cli/cli-flags.js#L500-L536","documentation":"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.","triggerScenarios":"Passing --screenEmulation.width, --screenEmulation.height, or --screenEmulation.deviceScaleFactor with a non-number value. For example: --screenEmulation.width=wide or --screenEmulation.deviceScaleFactor=high.","commonSituations":"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'.","solutions":["Pass bare numeric pixel values without units: --screenEmulation.width=360 (not '360px')","Ensure shell variables expand to numbers: WIDTH=360 && lighthouse --screenEmulation.width=$WIDTH","Use a preset that sets these values automatically: --preset=mobile"],"exampleFix":"# before\nlighthouse --screenEmulation.width=360px --screenEmulation.height=640px https://example.com\n# after\nlighthouse --screenEmulation.width=360 --screenEmulation.height=640 https://example.com","handlingStrategy":"validation","validationCode":"const NUMERIC_EMU_KEYS = ['width', 'height', 'deviceScaleFactor'];\nfunction validateScreenEmulationNumbers(value) {\n  for (const key of NUMERIC_EMU_KEYS) {\n    const v = value[key];\n    if (v !== undefined && typeof v !== 'number') {\n      throw new Error(`screenEmulation.${key} must be a number, got ${typeof v}`);\n    }\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pass bare pixel numbers without units: --screenEmulation.width=360 (not '360px')","Use presets to avoid manual emulation values","Quote nested flag values to ensure numeric coercion"],"tags":["cli","validation","emulation"],"backgroundTag":null,"analyzedSha":"9515cd4e58ebed69f78742d932b501c2cab8ad8f","analyzedAt":"2026-08-13T06:28:10.346Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}