{"record":{"id":"e6b3dc4c60cc0582","repo":"GoogleChrome/lighthouse","slug":"invalid-value-argument-screenemulation-must-be","errorCode":null,"errorMessage":"Invalid value: Argument 'screenEmulation' must be an object, specified per-property ('screenEmulation.width', 'screenEmulation.deviceScaleFactor', etc)","messagePattern":"Invalid value: Argument 'screenEmulation' must be an object, specified per-property \\('screenEmulation\\.width', 'screenEmulation\\.deviceScaleFactor', etc\\)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/cli-flags.js","lineNumber":503,"sourceCode":"      throw new Error(`Invalid value: 'throttling.${key}' must be a number`);\n    }\n    // Note: this works type-wise because the throttling settings all have the same type.\n    throttlingSettings[key] = possibleSetting;\n  }\n\n  return throttlingSettings;\n}\n\n/**\n * Take yarg's unchecked object value and ensure it is a proper LH.screenEmulationSettings.\n * @param {unknown} value\n * @return {Partial<LH.ScreenEmulationSettings>|undefined}\n */\nfunction coerceScreenEmulation(value) {\n  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","sourceCodeStart":485,"sourceCodeEnd":521,"githubUrl":"https://github.com/GoogleChrome/lighthouse/blob/9515cd4e58ebed69f78742d932b501c2cab8ad8f/cli/cli-flags.js#L485-L521","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use nested property syntax: --screenEmulation.mobile --screenEmulation.width=360 --screenEmulation.height=640","Use --preset=mobile or --preset=desktop to set emulation automatically","Disable emulation entirely: --screenEmulation.disabled"],"exampleFix":"# before\nlighthouse --screenEmulation=mobile https://example.com\n# after\nlighthouse --screenEmulation.mobile --screenEmulation.width=375 --screenEmulation.height=667 https://example.com","handlingStrategy":"validation","validationCode":"function validateScreenEmulation(value) {\n  if (value === undefined) return;\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n    throw new Error('--screenEmulation must be an object; use nested syntax like --screenEmulation.width=360');\n  }\n}","typeGuard":"/** @param {unknown} v */\nfunction isScreenEmulationObject(v) {\n  return typeof v === 'object' && v !== null && !Array.isArray(v);\n}","tryCatchPattern":null,"preventionTips":["Always use nested dot-syntax: --screenEmulation.mobile, --screenEmulation.width=360","Use --preset=mobile or --preset=desktop for sensible defaults","In the programmatic API, pass screenEmulation as an object"],"tags":["cli","validation","emulation"],"backgroundTag":null,"analyzedSha":"9515cd4e58ebed69f78742d932b501c2cab8ad8f","analyzedAt":"2026-08-13T06:28:10.346Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}