GoogleChrome/lighthouse · error · Error

unrecognized category in 'onlyCategories': ${unknown.join(',

Error message

unrecognized category in 'onlyCategories': ${unknown.join(', ')}

What it means

Thrown by errorOnUnknownOnlyCategories in filters.js. When settings.onlyCategories lists category ids, every id must exist as a key in the resolved config's categories. Lighthouse filters the run to those categories, so an unknown id is rejected rather than silently ignored. The message lists the offending ids.

Source

Thrown at core/config/filters.js:190

  const categoriesToKeep = Object.entries(categories)
    .filter(([categoryId]) => onlyCategories.includes(categoryId));
  return Object.fromEntries(categoriesToKeep);
}

/**
 * Throw an error if any specified onlyCategory is not a known category that can
 * be included.
 *
 * @param {LH.Config.ResolvedConfig['categories']} allCategories
 * @param {string[] | null} onlyCategories
 * @return {void}
 */
function errorOnUnknownOnlyCategories(allCategories, onlyCategories) {
  if (!onlyCategories) return;

  const unknown = onlyCategories.filter(c => !allCategories?.[c]);
  if (unknown.length) {
    throw new Error(`unrecognized category in 'onlyCategories': ${unknown.join(', ')}`);
  }
}

/**
 * Filters a categories object and their auditRefs down to the set that can be computed using
 * only the specified audits.
 *
 * @param {LH.Config.ResolvedConfig['categories']} categories
 * @param {Array<LH.Config.AuditDefn>} availableAudits
 * @return {LH.Config.ResolvedConfig['categories']}
 */
function filterCategoriesByAvailableAudits(categories, availableAudits) {
  if (!categories) return categories;

  const availableAuditIdToMeta = new Map(
    availableAudits.map(audit => [audit.implementation.meta.id, audit.implementation.meta])
  );

View on GitHub (pinned to 9515cd4e58)

Solutions

1. Correct the category id to match a key in the resolved config (e.g. 'performance','accessibility','seo').
2. If filtering to a plugin category, use its full id 'lighthouse-plugin-<name>'.
3. Print Object.keys(config.categories) to confirm valid ids before setting onlyCategories.

Example fix

// before
const flags = {onlyCategories: ['performnce']};
// after
const flags = {onlyCategories: ['performance']};

const known = new Set(Object.keys(resolvedConfig.categories || {}));
const unknown = (flags.onlyCategories || []).filter(c => !known.has(c));
if (unknown.length) throw new Error('Unknown onlyCategories: ' + unknown.join(', '));

function onlyCategoriesAreKnown(cats, known) {
  return Array.isArray(cats) && cats.every(c => known.has(c));
}

try { await lighthouse(url, flags, config); }
catch (e) { if (/unrecognized category in 'onlyCategories'/.test(e.message)) console.error(e.message); throw e; }

When it happens

Trigger: flags.onlyCategories = ['seo','typo-cat'] where 'typo-cat' is not a category id in the config. The filter collects ids not present in allCategories and filters.js:190 throws, naming them.

Common situations: Typo in a category id. Using onlyCategories with a config that does not include that category (e.g. a perf-only config). Category renamed/removed after a Lighthouse upgrade. Plugin category id mismatch (plugin ids are prefixed 'lighthouse-plugin-').

Related errors

• onlyCategories cannot be an empty array.
• onlyAudits cannot be an empty array.
• plugin name '${pluginName}' not allowed because it is the id
• ${pluginName} has an invalid category description.
• ${pluginName} has an invalid category manualDescription.

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