{"record":{"id":"74cfe9f30e2b7d46","repo":"GoogleChrome/lighthouse","slug":"invalid-value-argument-locale-must-be-a-string","errorCode":null,"errorMessage":"Invalid value: Argument 'locale' must be a string","messagePattern":"Invalid value: Argument 'locale' must be a string","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/cli-flags.js","lineNumber":432,"sourceCode":"\n  if (typeof value !== 'string' || !value || !fs.existsSync(path.dirname(value))) {\n    throw new Error(`--output-path (${value}) cannot be written to`);\n  }\n\n  return value;\n}\n\n/**\n * Verifies value is a string, then coerces type to LH.Locale for convenience. However, don't\n * allowlist specific locales. Why? So we can support the user who requests 'es-MX' (unsupported)\n * and we'll fall back to 'es' (supported).\n * @param {unknown} value\n * @return {LH.Locale|undefined}\n */\nfunction 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.","sourceCodeStart":414,"sourceCodeEnd":450,"githubUrl":"https://github.com/GoogleChrome/lighthouse/blob/9515cd4e58ebed69f78742d932b501c2cab8ad8f/cli/cli-flags.js#L414-L450","documentation":"The --locale flag sets the display language for Lighthouse's report. coerceLocale accepts any string value (Lighthouse deliberately does not allowlist specific locales so it can fall back, e.g., es-MX to es). This error fires only when the value is not undefined and not a string — a type violation rather than an invalid locale.","triggerScenarios":"Passing --locale with a value that yargs resolves to a non-string type (number, boolean, object). For example, a value that parses as a number or is passed programmatically as a non-string.","commonSituations":"Programmatic yargs configuration passing a non-string locale; shell expansion edge cases; unusual flag syntax that causes yargs to coerce the value to a non-string type.","solutions":["Pass the locale as a quoted string: --locale=en or --locale=es","If using the programmatic API, pass locale as a string in the flags object: {locale: 'en'}","Remove the flag to use Lighthouse's default locale detection"],"exampleFix":"# before (edge case where value is non-string)\n# --locale passed with a numeric value\n# after\nlighthouse --locale=en https://example.com","handlingStrategy":"type-guard","validationCode":"function validateLocale(value) {\n  if (value !== undefined && typeof value !== 'string') {\n    throw new Error(`--locale must be a string, got ${typeof value}`);\n  }\n}","typeGuard":"/** @param {unknown} v */\nfunction isLocaleString(v) {\n  return v === undefined || typeof v === 'string';\n}","tryCatchPattern":null,"preventionTips":["Pass locale as a lowercase string: --locale=en or --locale=es","When using the programmatic API, set locale in the flags object as a string"],"tags":["cli","validation","i18n"],"backgroundTag":null,"analyzedSha":"9515cd4e58ebed69f78742d932b501c2cab8ad8f","analyzedAt":"2026-08-13T06:28:10.346Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}