{"record":{"id":"f440b180961a66f2","repo":"GoogleChrome/lighthouse","slug":"invalid-value-argument-extra-headers-must-be-a","errorCode":null,"errorMessage":"Invalid value: Argument 'extra-headers' must be a string","messagePattern":"Invalid value: Argument 'extra-headers' must be a string","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/cli-flags.js","lineNumber":447,"sourceCode":"function coerceLocale(value) {\n  if (value === undefined) return;\n\n  if (typeof value !== 'string') throw new Error(`Invalid value: Argument 'locale' must be a string`);\n  return /** @type {LH.Locale} */ (value);\n}\n\n/**\n * `--extra-headers` comes in as a JSON string or a path to a JSON string, but the flag value\n * needs to be the parsed object. Load file (if necessary) and returns the parsed object.\n * @param {unknown} value\n * @return {LH.SharedFlagsSettings['extraHeaders']}\n */\nfunction coerceExtraHeaders(value) {\n  // TODO: this function does not actually verify the object type.\n  if (value === undefined) return value;\n  if (typeof value === 'object') return /** @type {LH.SharedFlagsSettings['extraHeaders']} */ (value);\n  if (typeof value !== 'string') {\n    throw new Error(`Invalid value: Argument 'extra-headers' must be a string`);\n  }\n\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","sourceCodeStart":429,"sourceCodeEnd":465,"githubUrl":"https://github.com/GoogleChrome/lighthouse/blob/9515cd4e58ebed69f78742d932b501c2cab8ad8f/cli/cli-flags.js#L429-L465","documentation":"The --extra-headers flag accepts either a JSON object string (inline) or a path to a JSON file. coerceExtraHeaders first allows undefined and object types, then requires any remaining value to be a string (which is then parsed as JSON or read from a file path). This error fires when the value is a type other than undefined, object, or string — e.g., a number or boolean.","triggerScenarios":"Passing --extra-headers with a value that yargs resolves to neither undefined, an object, nor a string. For example, a numeric value or a boolean that bypasses yargs's own type handling and reaches the coerce function.","commonSituations":"Programmatic yargs usage passing a non-string/non-object value; unusual flag syntax causing type coercion issues; shell quoting edge cases that produce unexpected types.","solutions":["Pass extra headers as an inline JSON string: --extra-headers='{\"Authorization\":\"Bearer token\"}'","Pass a path to a JSON file: --extra-headers=./headers.json","When using the programmatic API, pass the parsed object directly in flags: {extraHeaders: {Authorization: 'Bearer token'}}"],"exampleFix":"# before\nlighthouse --extra-headers=12345 https://example.com\n# after\nlighthouse --extra-headers='{\"X-Custom-Header\":\"value\"}' https://example.com","handlingStrategy":"validation","validationCode":"// Validate extra-headers before passing to Lighthouse\nfunction validateExtraHeaders(value) {\n  if (value === undefined) return;\n  if (typeof value === 'object') return; // already parsed object\n  if (typeof value !== 'string') {\n    throw new Error('--extra-headers must be a JSON string or file path');\n  }\n  // Optionally pre-validate JSON\n  if (value.startsWith('{')) JSON.parse(value);\n}","typeGuard":"/** @param {unknown} v */\nfunction isExtraHeadersValue(v) {\n  return v === undefined || typeof v === 'object' || typeof v === 'string';\n}","tryCatchPattern":null,"preventionTips":["Pass extra headers as a JSON object string: --extra-headers='{\"key\":\"value\"}'","Alternatively point to a JSON file: --extra-headers=./headers.json","In the programmatic API, pass the parsed object directly: {extraHeaders: {key: 'value'}}"],"tags":["cli","validation","network","headers"],"backgroundTag":null,"analyzedSha":"9515cd4e58ebed69f78742d932b501c2cab8ad8f","analyzedAt":"2026-08-13T06:28:10.346Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}