What causes "Incorrectly formatted @example: "${rawExample}"" in GoogleChrome/lighthouse?

Re-read the @example tag and ensure it is exactly `{exampleValue} placeholderName` with a single space after the closing brace.

GoogleChrome/lighthouse · error

Incorrectly formatted @example: "${rawExample}"

Error message

Incorrectly formatted @example: "${rawExample}"

What it means

Thrown by parseExampleJsDoc() when an @example tag's content does not match the rigid pattern `{exampleValue} placeholderName`. The i18n pipeline uses @example to declare placeholder example values, and this regex enforces that contract. Any deviation in spacing, brace placement, or missing placeholder name triggers it.

Source

Thrown at core/scripts/i18n/collect-strings.js:127

  // The non-string types were introduced in https://github.com/microsoft/TypeScript/pull/41877
  // Not currently used, but utility `getTextOfJSDocComment` will convert if the types switch over.
  if (typeof comment !== 'string') {
    throw new Error(`unsupported JSDoc comment: ${JSON.stringify(comment)}`);
  }

  // Line breaks within a jsdoc comment should always be replaceable with a space.
  return comment.replace(/\n+/g, ' ').trim();
}

/**
 * Parses a string of the form `{exampleValue} placeholderName`, parsed by tsc
 * as the content of an `@example` tag.
 * @param {string} rawExample
 * @return {{placeholderName: string, exampleValue: string}}
 */
function parseExampleJsDoc(rawExample) {
  const match = rawExample.match(/^{(?<exampleValue>[^}]+)} (?<placeholderName>.+)$/);
  if (!match || !match.groups) throw new Error(`Incorrectly formatted @example: "${rawExample}"`);
  const {placeholderName, exampleValue} = match.groups;
  return {placeholderName, exampleValue};
}

/**
 * Take a series of LHL format ICU messages and converts them
 * to CTC format by replacing {ICU} and `markdown` with
 * $placeholders$. Functional opposite of `bakePlaceholders`. This is commonly
 * called as one of the first steps in translation, via collect-strings.js.
 *
 * Converts this:
 * messages: {
 *  "core/audits/seo/canonical.js | explanationDifferentDomain" {
 *    "message": "Points to a different domain ({url})",
 *    },
 *  },
 * }
 *

View on GitHub (pinned to 9515cd4e58)

Solutions

Re-read the @example tag and ensure it is exactly `{exampleValue} placeholderName` with a single space after the closing brace.
Check that exampleValue contains no `}` characters and placeholderName is non-empty.
Run collect-strings locally to surface the exact failing string before committing.

Example fix

// before
 * @example {https://example.com}url
// after
 * @example {https://example.com} url

Defensive patterns

Strategy: validation

Validate before calling

const EXAMPLE_RE = /^\{(?<exampleValue>[^}]+)} (?<placeholderName>.+)$/;
function isValidExample(raw) { return EXAMPLE_RE.test(raw); }

Type guard

/** @param {string} raw @returns {boolean} */
function isValidExampleFormat(raw) { return /^\{[^}]+} .+$/.test(raw); }

Try / catch

if (!isValidExampleFormat(rawExample)) {
  console.warn(`Skipping malformed @example: ${rawExample}`);
  continue;
}
const {placeholderName, exampleValue} = parseExampleJsDoc(rawExample);

Prevention

Always write @example as `{value} placeholderName` with exactly one space after the closing brace.
Add a lint rule or pre-commit hook that validates @example tags against the regex.
Run collect-strings locally before pushing i18n changes.

When it happens

Trigger: Authoring a UIStrings entry whose @example tag is written as `{value}name` (no space), `value placeholder` (no braces), `{value}` (no placeholder name), or multiline example content that collapses to something not matching the regex.

Common situations: Copy-pasting example syntax from elsewhere that uses a different convention; typos in braces or forgetting the placeholder name; IDE auto-formatting stripping the required space.

Related errors

AI-assisted analysis of GoogleChrome/lighthouse@9515cd4e58 (2026-08-13). Data as JSON: /api/errors/17c12c4fd5eabf76. Report an issue: GitHub.