GoogleChrome/lighthouse · error · Error

plugin name '${pluginName}' does not start with 'lighthouse-

Error message

plugin name '${pluginName}' does not start with 'lighthouse-plugin-'

What it means

Thrown by assertValidPluginName in validation.js. A Lighthouse plugin's name must begin with the prefix 'lighthouse-plugin-'. An optional npm scope prefix (one '/') is stripped first, so '@scope/lighthouse-plugin-foo' is allowed. Any name not starting with the required prefix after scope-stripping is rejected, so plugins are namespaced predictably.

Source

Thrown at core/config/validation.js:45

  // A snapshot artifact cannot depend on a timespan/navigation artifact because it might run without a timespan.
  if (dependentLevel === levels.snapshot) return dependencyLevel === levels.snapshot;
  // A navigation artifact can depend on anything.
  return true;
}

/**
 * Throws if pluginName is invalid or (somehow) collides with a category in the
 * config being added to.
 * @param {LH.Config} config
 * @param {string} pluginName
 */
function assertValidPluginName(config, pluginName) {
  const parts = pluginName.split('/');
  if (parts.length === 2) {
    pluginName = parts[1];
  }
  if (!pluginName.startsWith('lighthouse-plugin-')) {
    throw new Error(`plugin name '${pluginName}' does not start with 'lighthouse-plugin-'`);
  }

  if (config.categories?.[pluginName]) {
    throw new Error(`plugin name '${pluginName}' not allowed because it is the id of a category already found in config`); // eslint-disable-line max-len
  }
}

/**
 * Throws an error if the provided object does not implement the required gatherer interface.
 * @param {LH.Config.AnyArtifactDefn} artifactDefn
 */
function assertValidArtifact(artifactDefn) {
  const gatherer = artifactDefn.gatherer.instance;

  if (typeof gatherer.meta !== 'object') {
    throw new Error(`Gatherer for ${artifactDefn.id} did not provide a meta object.`);
  }

View on GitHub (pinned to 9515cd4e58)

Solutions

1. Name/publish the plugin with the prefix: 'lighthouse-plugin-myplugin' (or '@scope/lighthouse-plugin-myplugin').
2. Update config.plugins to use the prefixed name exactly.
3. Ensure the package's main export also uses the prefixed id internally.

Example fix

// before
plugins: ['my-plugin']
// after
plugins: ['lighthouse-plugin-myplugin']

function assertPluginName(name) {
  const base = name.split('/').pop();
  if (!base.startsWith('lighthouse-plugin-')) {
    throw new Error(`Plugin '${name}' must start with 'lighthouse-plugin-'`);
  }
}
config.plugins.forEach(assertPluginName);

function isValidPluginName(name) {
  const parts = name.split('/');
  const base = parts.length === 2 ? parts[1] : name;
  return base.startsWith('lighthouse-plugin-');
}

try { await lighthouse(url, flags, config); }
catch (e) { if (/does not start with 'lighthouse-plugin-'/.test(e.message)) console.error('Rename plugin with the required prefix'); throw e; }

When it happens

Trigger: Adding plugin 'my-plugin' or '@scope/my-plugin' to config.plugins. After splitting on '/', the name does not start with 'lighthouse-plugin-', so validation.js:45 throws.

Common situations: Forgetting the required 'lighthouse-plugin-' prefix when naming/publishing a plugin. Using a short alias in plugins array. Mismatch between the npm package name and the plugin name Lighthouse expects.

Related errors

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

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