What causes "${pluginName} groups json is not defined as an object." in GoogleChrome/lighthouse?

Define groups as an object keyed by group id: groups: {a: {title:'A'}, b: {title:'B'}}.

GoogleChrome/lighthouse · error · Error

${pluginName} groups json is not defined as an object.

Error message

${pluginName} groups json is not defined as an object.

What it means

Thrown by ConfigPlugin._parseGroups when a plugin defines a 'groups' key whose value is not a plain object (isObjectOfUnknownProperties fails: must be typeof 'object', not null, not an array). groups must be a map of groupId -> groupJson. undefined is allowed (groups omitted); everything else non-object is not.

Source

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

      manualDescription: manualDescription,
      supportedModes,
    };
  }


  /**
   * Extract and validate groups JSON added by the plugin.
   * @param {unknown} groupsJson
   * @param {string} pluginName
   * @return {Record<string, LH.Config.GroupJson>|undefined}
   */
  static _parseGroups(groupsJson, pluginName) {
    if (groupsJson === undefined) {
      return undefined;
    }

    if (!isObjectOfUnknownProperties(groupsJson)) {
      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.`);

View on GitHub (pinned to 9515cd4e58)

Solutions

Define groups as an object keyed by group id: groups: {a: {title:'A'}, b: {title:'B'}}.
Remove the groups key entirely if the plugin has no groups.

Example fix

// before
module.exports = {groups: [{title:'A'}], category:{...}};
// after
module.exports = {groups: {groupA: {title:'A'}}, category:{...}};

Defensive patterns

Strategy: validation

Validate before calling

function isPlainObject(v) { return typeof v === 'object' && v !== null && !Array.isArray(v); }
if (plugin.groups !== undefined && !isPlainObject(plugin.groups)) {
  throw new TypeError('groups must be an object map of groupId -> group');
}

Type guard

function isGroupMap(v) {
  if (v === undefined) return true;
  if (typeof v !== 'object' || v === null || Array.isArray(v)) return false;
  return Object.values(v).every(g => typeof g === 'object' && g !== null && !Array.isArray(g));
}

Try / catch

try { await ConfigPlugin.parsePlugin(plugin, name); }
catch (e) { if (/groups json is not defined as an object/.test(e.message)) console.error('Make groups a keyed object'); throw e; }

Prevention

Model groups as {id: {title,...}}, never as an array.
Omit groups when the plugin has none.

When it happens

Trigger: Plugin exports groups: [...] (an array) or groups: null or groups: 'groupA'. _parseGroups sees it is not undefined and not a plain object, so config-plugin.js:190 throws.

Common situations: Confusing groups (a keyed map) with an array. Setting groups: null to mean 'no groups'. JSON config where groups was written as a list.

Related errors

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