GoogleChrome/lighthouse · error · Error

${pluginName} has an invalid category description.

Error message

${pluginName} has an invalid category description.

What it means

Thrown by ConfigPlugin._parseCategory while validating a Lighthouse plugin's 'category' block. The 'description' field is optional, but when present it must be a string or an i18n ICU message object (i18n.isStringOrIcuMessage). Lighthouse enforces this so every category description is renderable in the report UI. A number, boolean, array, or plain object triggers the error.

Source

Thrown at core/config/config-plugin.js:155

      throw new Error(`${pluginName} has no valid category.`);
    }

    const {
      title,
      description,
      manualDescription,
      auditRefs: auditRefsJson,
      supportedModes,
      ...invalidRest
    } = categoryJson;

    assertNoExcessProperties(invalidRest, pluginName, 'category');

    if (!i18n.isStringOrIcuMessage(title)) {
      throw new Error(`${pluginName} has an invalid category tile.`);
    }
    if (!i18n.isStringOrIcuMessage(description) && description !== undefined) {
      throw new Error(`${pluginName} has an invalid category description.`);
    }
    if (!i18n.isStringOrIcuMessage(manualDescription) && manualDescription !== undefined) {
      throw new Error(`${pluginName} has an invalid category manualDescription.`);
    }
    if (!isArrayOfGatherModes(supportedModes) && supportedModes !== undefined) {
      throw new Error(
        `${pluginName} supportedModes must be an array, ` +
        `valid array values are "navigation", "timespan", and "snapshot".`
      );
    }
    const auditRefs = ConfigPlugin._parseAuditRefsList(auditRefsJson, pluginName);

    return {
      title,
      auditRefs,
      description: description,
      manualDescription: manualDescription,
      supportedModes,

View on GitHub (pinned to 9515cd4e58)

Solutions

1. Set category.description to a plain string, e.g. description: 'Details about this category.'
2. If using i18n, pass an ICU message created via i18n.createMessageInstanceIdFn / UIStrings so isStringOrIcuMessage returns true.
3. Omit the description field entirely if you do not need it (undefined is allowed).
4. Check the resolved type of description after loading your plugin JSON (e.g. typeof description) before Lighthouse processes it.

Example fix

// before
module.exports = {
  category: {title: 'SEO', description: {text: 'seo stuff'}, auditRefs: [{id: 'x', weight: 1}]}
};
// after
module.exports = {
  category: {title: 'SEO', description: 'SEO checks for the page.', auditRefs: [{id: 'x', weight: 1}]}
};

// Validate a plugin category block before passing to Lighthouse
const i18n = require('lighthouse/core/lib/i18n/i18n.js');
function validateCategory(cat) {
  if (cat.description !== undefined && !i18n.isStringOrIcuMessage(cat.description)) {
    throw new TypeError('category.description must be a string or IcuMessage');
  }
}
validateCategory(plugin.category);

function isStringOrUndefined(v) {
  return v === undefined || typeof v === 'string' || (v && typeof v === 'object' && typeof v.i18nId === 'string');
}

try {
  const config = await ConfigPlugin.parsePlugin(pluginJson, name);
} catch (e) {
  if (/invalid category description/.test(e.message)) {
    console.error('Fix plugin.category.description to be a string');
  }
  throw e;
}

When it happens

Trigger: A plugin module exports `module.exports = {category: {title: 'My Cat', description: 123, auditRefs: [...]}}`. The `description` value (123) is not undefined and fails isStringOrIcuMessage (typeof !== 'string' and not an IcuMessage), so config-plugin.js:155 throws.

Common situations: Authoring a custom lighthouse-plugin-* package and setting description to a non-string (e.g. an object, a number, or a YAML-parsed value that became a different type). Copying a category JSON where description was accidentally left as null or an object. Loading plugin config from JSON where a typo produced a wrong type.

Related errors

• ${pluginName} has an invalid category manualDescription.
• ${pluginName} has an invalid group title.
• ${pluginName} has an invalid group description.
• ${pluginName} supportedModes must be an array, valid array v
• ${pluginName} groups json is not defined as an object.

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