What causes "${pluginName} has an invalid group description." in GoogleChrome/lighthouse?

Set description to a string: {title:'A', description: 'What this group covers.'}

GoogleChrome/lighthouse · error · Error

${pluginName} has an invalid group description.

Error message

${pluginName} has an invalid group description.

What it means

Thrown by ConfigPlugin._parseGroups when a group's optional 'description' is present but is not a string or ICU message. description may be omitted (undefined), but any other non-string type (number, object, array, boolean) fails i18n.isStringOrIcuMessage.

Source

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

      throw new Error(`${pluginName} groups json is not defined as an object.`);
    }

    const groups = Object.entries(groupsJson);

    /** @type {Record<string, LH.Config.GroupJson>} */
    const parsedGroupsJson = {};
    groups.forEach(([groupId, groupJson]) => {
      if (!isObjectOfUnknownProperties(groupJson)) {
        throw new Error(`${pluginName} has a group not defined as an object.`);
      }
      const {title, description, ...invalidRest} = groupJson;
      assertNoExcessProperties(invalidRest, pluginName, 'group');

      if (!i18n.isStringOrIcuMessage(title)) {
        throw new Error(`${pluginName} has an invalid group title.`);
      }
      if (!i18n.isStringOrIcuMessage(description) && description !== undefined) {
        throw new Error(`${pluginName} has an invalid group description.`);
      }
      parsedGroupsJson[`${pluginName}-${groupId}`] = {
        title,
        description,
      };
    });
    return parsedGroupsJson;
  }

  /**
   * Extracts and validates a config from the provided plugin input, throwing
   * if it deviates from the expected object shape.
   * @param {unknown} pluginJson
   * @param {string} pluginName
   * @return {LH.Config}
   */
  static parsePlugin(pluginJson, pluginName) {
    // Clone to prevent modifications of original and to deactivate any live properties.

View on GitHub (pinned to 9515cd4e58)

Solutions

Set description to a string: {title:'A', description: 'What this group covers.'}
Omit description if not needed.

Example fix

// before
groups: {a: {title:'A', description: true}}
// after
groups: {a: {title:'A', description: 'Group A audits.'}}

Defensive patterns

Strategy: validation

Validate before calling

const i18n = require('lighthouse/core/lib/i18n/i18n.js');
for (const [id, g] of Object.entries(plugin.groups || {})) {
  if (g.description !== undefined && !i18n.isStringOrIcuMessage(g.description)) {
    throw new TypeError(`group '${id}' description must be a string`);
  }
}

Type guard

function groupDescriptionOk(g) { return g.description === undefined || typeof g.description === 'string'; }

Try / catch

try { await ConfigPlugin.parsePlugin(plugin, name); }
catch (e) { if (/invalid group description/.test(e.message)) console.error('group.description must be a string'); throw e; }

Prevention

Keep group.description a string or omit it.
Never use booleans/objects for description.

When it happens

Trigger: groups: {groupA: {title:'A', description: 42}} or description: false. Not undefined and not a string/IcuMessage, so config-plugin.js:208 throws.

Common situations: Setting description to a boolean or object. Leftover placeholder values. Confusing description with a structured object.

Related errors

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