GoogleChrome/lighthouse · error · Error

Unrecognized screenEmulation option: ${key}

Error message

Unrecognized screenEmulation option: ${key}

What it means

Within coerceScreenEmulation's switch statement, the default case handles any key in the iteration that doesn't match width, height, deviceScaleFactor, mobile, or disabled. In practice this case is effectively unreachable because the keys array iterated is a hardcoded constant containing only those five keys. The error would only fire if the hardcoded keys array were extended with a new key without adding a corresponding switch case.

Source

Thrown at cli/cli-flags.js:538

        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. If you are a Lighthouse contributor who hit this, add a matching case to the switch statement in coerceScreenEmulation for the new key
2. If you are an end user, this error indicates a bug in your Lighthouse build — report it or use an official release
3. No end-user CLI input can trigger this error

When it happens

Trigger: This error is not triggerable through normal CLI usage. It would only occur if a developer modified the keys array in coerceScreenEmulation to include a new property name without adding a matching case to the switch statement. It is a defensive guard against incomplete code changes within Lighthouse itself.

Common situations: Contributing to Lighthouse and adding a new screenEmulation property to the keys array without updating the switch; forking Lighthouse and extending screenEmulation settings incompletely.

Related errors

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