{"record":{"id":"f1b833ede8fa7f6b","repo":"GoogleChrome/lighthouse","slug":"invalid-value-argument-throttling-must-be-an-ob","errorCode":null,"errorMessage":"Invalid value: Argument 'throttling' must be an object, specified per-property ('throttling.rttMs', 'throttling.throughputKbps', etc)","messagePattern":"Invalid value: Argument 'throttling' must be an object, specified per-property \\('throttling\\.rttMs', 'throttling\\.throughputKbps', etc\\)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/cli-flags.js","lineNumber":467,"sourceCode":"\n  // (possibly) load and parse extra headers from JSON.\n  if (!value.startsWith('{')) {\n    // If not a JSON object, assume it's a path to a JSON file.\n    return JSON.parse(fs.readFileSync(value, 'utf-8'));\n  }\n  return JSON.parse(value);\n}\n\n/**\n * Take yarg's unchecked object value and ensure it's proper throttling settings.\n * @param {unknown} value\n * @return {LH.ThrottlingSettings|undefined}\n */\nfunction coerceThrottling(value) {\n  if (value === undefined) return;\n\n  if (!isObjectOfUnknownValues(value)) {\n    throw new Error(`Invalid value: Argument 'throttling' must be an object, specified per-property ('throttling.rttMs', 'throttling.throughputKbps', etc)`);\n  }\n\n  /** @type {Array<keyof LH.ThrottlingSettings>} */\n  const throttlingKeys = [\n    'rttMs',\n    'throughputKbps',\n    'requestLatencyMs',\n    'downloadThroughputKbps',\n    'uploadThroughputKbps',\n    'cpuSlowdownMultiplier',\n  ];\n\n  /** @type {LH.ThrottlingSettings} */\n  const throttlingSettings = {};\n  for (const key of throttlingKeys) {\n    const possibleSetting = value[key];\n    if (possibleSetting !== undefined && typeof possibleSetting !== 'number') {\n      throw new Error(`Invalid value: 'throttling.${key}' must be a number`);","sourceCodeStart":449,"sourceCodeEnd":485,"githubUrl":"https://github.com/GoogleChrome/lighthouse/blob/9515cd4e58ebed69f78742d932b501c2cab8ad8f/cli/cli-flags.js#L449-L485","documentation":"The --throttling flag accepts per-property settings as a nested object (e.g., --throttling.rttMs=150). coerceThrottling validates that the aggregated value from yargs is a plain object via isObjectOfUnknownValues. This error fires when the top-level throttling value is not an object at all — for instance, a string, number, or array.","triggerScenarios":"Passing --throttling as a single non-object value rather than using nested property syntax. For example: --throttling=fast or --throttling=150 instead of --throttling.rttMs=150. Yargs's nested-property coercion produces an object when dot-syntax is used; a bare value produces a non-object.","commonSituations":"Misunderstanding the throttling flag syntax and passing a bare value instead of nested properties; using a preset name directly; shell quoting that collapses the dot-syntax.","solutions":["Use nested property syntax: --throttling.rttMs=150 --throttling.throughputKbps=1638.40","Use a preset instead: --preset=desktop or --preset=perf (which sets throttling automatically)","Quote the flag properly if shell is consuming dots: --throttling.cpuSlowdownMultiplier=4"],"exampleFix":"# before\nlighthouse --throttling=fast https://example.com\n# after\nlighthouse --throttling.rttMs=150 --throttling.throughputKbps=1638.40 --throttling.cpuSlowdownMultiplier=4 https://example.com","handlingStrategy":"validation","validationCode":"// Validate throttling is an object with numeric properties\nfunction validateThrottling(value) {\n  if (value === undefined) return;\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n    throw new Error('--throttling must be an object; use nested syntax like --throttling.rttMs=150');\n  }\n}","typeGuard":"/** @param {unknown} v */\nfunction isThrottlingObject(v) {\n  return typeof v === 'object' && v !== null && !Array.isArray(v);\n}","tryCatchPattern":null,"preventionTips":["Always use nested dot-syntax: --throttling.rttMs=150, not --throttling=150","Use --preset=mobile or --preset=desktop to avoid manual throttling entirely","In the programmatic API, pass throttling as an object: {throttling: {rttMs: 150}}"],"tags":["cli","validation","throttling","performance"],"backgroundTag":null,"analyzedSha":"9515cd4e58ebed69f78742d932b501c2cab8ad8f","analyzedAt":"2026-08-13T06:28:10.346Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}