{"record":{"id":"1a9dadfb1b3f283a","repo":"GoogleChrome/lighthouse","slug":"invalid-value-screenemulation-key-must-be-a-1a9dad","errorCode":null,"errorMessage":"Invalid value: 'screenEmulation.${key}' must be a boolean","messagePattern":"Invalid value: 'screenEmulation\\.(.+?)' must be a boolean","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/cli-flags.js","lineNumber":533,"sourceCode":"      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;\n      default:\n        throw new Error(`Unrecognized screenEmulation option: ${key}`);\n    }\n  }\n\n  return screenEmulationSettings;\n}\n\nexport {\n  getFlags,\n  getYargsParser,\n};\n","sourceCodeStart":515,"sourceCodeEnd":549,"githubUrl":"https://github.com/GoogleChrome/lighthouse/blob/9515cd4e58ebed69f78742d932b501c2cab8ad8f/cli/cli-flags.js#L515-L549","documentation":"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.","triggerScenarios":"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.","commonSituations":"Using 'yes'/'no' or '1'/'0' instead of 'true'/'false'; shell variable expansion producing unexpected values; misunderstanding the accepted boolean string forms.","solutions":["Use --screenEmulation.mobile or --screenEmulation.disabled as bare flags (sets to true)","Use explicit 'true'/'false' strings: --screenEmulation.mobile=true or --screenEmulation.mobile=false","Use --no-screenEmulation.mobile for false (if supported by yargs), or --screenEmulation.mobile=false"],"exampleFix":"# before\nlighthouse --screenEmulation.mobile=yes --screenEmulation.disabled=0 https://example.com\n# after\nlighthouse --screenEmulation.mobile --screenEmulation.disabled=false https://example.com","handlingStrategy":"validation","validationCode":"const BOOL_EMU_KEYS = ['mobile', 'disabled'];\nfunction validateScreenEmulationBooleans(value) {\n  for (const key of BOOL_EMU_KEYS) {\n    const v = value[key];\n    if (v !== undefined && v !== true && v !== false && v !== 'true' && v !== 'false') {\n      throw new Error(`screenEmulation.${key} must be a boolean or 'true'/'false', got ${v}`);\n    }\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use bare flags for boolean true: --screenEmulation.mobile","Use explicit 'true'/'false' strings when a value is needed","Avoid 'yes'/'no'/'1'/'0' which are not accepted"],"tags":["cli","validation","emulation"],"backgroundTag":null,"analyzedSha":"9515cd4e58ebed69f78742d932b501c2cab8ad8f","analyzedAt":"2026-08-13T06:28:10.346Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}