Maximum plugin limit (${this.config.maxPlugins}) reached

Error message

Maximum plugin limit (${this.config.maxPlugins}) reached

What it means

Thrown by EnhancedPluginRegistry.register() when config.maxPlugins is set and plugins.size has already reached it. This is a capacity guard on the registry instance (default config may leave it undefined, in which case the check never fires), evaluated after the duplicate-name check and before version compatibility.

Source

Thrown at v3/@claude-flow/plugins/src/registry/enhanced-plugin-registry.ts:297

    // Resolve factory if needed
    const resolvedPlugin = typeof plugin === 'function' ? await plugin() : plugin;

    // Validate plugin
    if (!validatePlugin(resolvedPlugin)) {
      throw new Error('Invalid plugin: does not implement IPlugin interface');
    }

    const name = resolvedPlugin.metadata.name;
    const version = resolvedPlugin.metadata.version;

    // Check for duplicates
    if (this.plugins.has(name)) {
      throw new Error(`Plugin ${name} already registered`);
    }

    // Check max plugins
    if (this.config.maxPlugins && this.plugins.size >= this.config.maxPlugins) {
      throw new Error(`Maximum plugin limit (${this.config.maxPlugins}) reached`);
    }

    // Check core version compatibility
    if (resolvedPlugin.metadata.minCoreVersion) {
      if (!satisfiesVersion(`>=${resolvedPlugin.metadata.minCoreVersion}`, this.config.coreVersion)) {
        throw new Error(
          `Plugin ${name} requires core version >= ${resolvedPlugin.metadata.minCoreVersion}, ` +
          `but current version is ${this.config.coreVersion}`
        );
      }
    }
    if (resolvedPlugin.metadata.maxCoreVersion) {
      if (!satisfiesVersion(`<=${resolvedPlugin.metadata.maxCoreVersion}`, this.config.coreVersion)) {
        throw new Error(
          `Plugin ${name} requires core version <= ${resolvedPlugin.metadata.maxCoreVersion}, ` +
          `but current version is ${this.config.coreVersion}`
        );
      }

View on GitHub (pinned to fa13ee4ad6)

Solutions

Raise or remove maxPlugins in the registry config if the plugin count is legitimately growing
Unregister unused plugins before registering new ones to stay under the cap
Audit what is registered (registry list API / logs 'Plugin registered: ...') to find plugins you did not intend to load

Example fix

// before
const registry = new EnhancedPluginRegistry({ coreVersion: '3.0.0', maxPlugins: 5 });
// 6th register() -> throws Maximum plugin limit (5) reached

// after
const registry = new EnhancedPluginRegistry({ coreVersion: '3.0.0', maxPlugins: 20 });

Defensive patterns

Strategy: validation

Validate before calling

const registered = await registry.list();
if (registryConfig.maxPlugins !== undefined && registered.length >= registryConfig.maxPlugins) {
  // free slots or fail loudly before register() throws
  for (const stale of pickStalePlugins(registered)) {
    await registry.unregister(stale.metadata.name);
  }
}
await registry.register(plugin);

Prevention

Size maxPlugins against the plugin count you actually deploy, with headroom
Log registrations ('Plugin registered: ...') so creeping plugin counts are visible before the cap bites
Prefer unregistering unused plugins over endlessly raising the cap

When it happens

Trigger: Creating EnhancedPluginRegistry with config { maxPlugins: 10 } and registering an 11th plugin; dynamically discovering and registering plugins at runtime until the cap is hit; copying a config preset with a low maxPlugins into a workload that legitimately needs more plugins.

Common situations: Right-sizing a registry for one deployment then reusing the config in a bigger one; plugins auto-registered per tenant/feature accumulating beyond the intended cap; a cap added defensively during development left in production config.

Related errors

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/3e9a05dc4cedc41c. Report an issue: GitHub.