{"record":{"id":"cd29b2e108c55a53","repo":"ruvnet/ruflo","slug":"plugin-name-mismatch-expected-name-got-reso","errorCode":null,"errorMessage":"Plugin name mismatch: expected ${name}, got ${resolved.metadata.name}","messagePattern":"Plugin name mismatch: expected (.+?), got (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/plugins/src/registry/enhanced-plugin-registry.ts","lineNumber":560,"sourceCode":"    let state: unknown;\n    if (options?.preserveState && (entry.plugin as any).getState) {\n      state = await (entry.plugin as any).getState();\n    }\n\n    // Shutdown old plugin\n    if (entry.plugin.state === 'initialized') {\n      await entry.plugin.shutdown();\n    }\n\n    // Resolve and validate new plugin\n    const resolved = typeof newPlugin === 'function' ? await newPlugin() : newPlugin;\n    if (!validatePlugin(resolved)) {\n      throw new Error('Invalid plugin replacement');\n    }\n\n    // Verify same name\n    if (resolved.metadata.name !== name) {\n      throw new Error(`Plugin name mismatch: expected ${name}, got ${resolved.metadata.name}`);\n    }\n\n    // Update dependency graph\n    const dependencies = this.parseDependencies(resolved.metadata.dependencies);\n    this.dependencyGraph.removePlugin(name);\n    this.dependencyGraph.addPlugin(name, resolved.metadata.version, dependencies);\n\n    // Initialize new plugin\n    const context = this.createPluginContext(entry);\n    const timeout = options?.timeout ?? this.config.loadTimeout ?? 30000;\n\n    await Promise.race([\n      resolved.initialize(context),\n      new Promise<never>((_, reject) =>\n        setTimeout(() => reject(new Error('Hot reload timeout')), timeout)\n      ),\n    ]);\n","sourceCodeStart":542,"sourceCodeEnd":578,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/plugins/src/registry/enhanced-plugin-registry.ts#L542-L578","documentation":"Thrown by EnhancedPluginRegistry.reload(name, newPlugin) when the replacement passes validation but its metadata.name differs from the name argument. reload is an in-place hot swap keyed by name (it removes and re-adds the same node in the dependency graph), so the replacement must keep the identity of the plugin it replaces; a different name would silently change who depends on whom.","triggerScenarios":"reload('logger', newPlugin) where newPlugin.metadata.name is 'logger-v2'; copy-pasting a plugin and forgetting to update metadata.name before hot-swapping it in; reload tooling passing a file or alias name that differs from the replacement's internal name.","commonSituations":"Major-version plugin rewrite that renames the plugin; build tooling generating plugins with suffixed names; CI hot-reload of a differently-named artifact.","solutions":["Set the replacement's metadata.name to exactly the registered plugin's name before reload","If you intend a rename, do it explicitly: unregister the old name and register the new plugin (updating dependents' declarations accordingly)","Assert the name matches in your build or verification step before shipping the hot-swap artifact"],"exampleFix":"// before\nawait registry.reload('logger', loggerV2); // loggerV2.metadata.name === 'logger-v2' -> throws\n\n// after\nloggerV2.metadata.name = 'logger'; // keep identity for hot-swap\nawait registry.reload('logger', loggerV2);","handlingStrategy":"validation","validationCode":"const resolved = typeof newPlugin === 'function' ? await newPlugin() : newPlugin;\nif (resolved.metadata.name !== name) {\n  throw new Error(\n    `reload target '${name}' but replacement is '${resolved.metadata.name}'; ` +\n    'use unregister+register for renames'\n  );\n}\nawait registry.reload(name, resolved);","typeGuard":null,"tryCatchPattern":"try {\n  await registry.reload(name, newPlugin);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Plugin name mismatch')) {\n    // intended rename: fall back to an explicit swap\n    await registry.unregister(name);\n    await registry.register(resolved);\n  } else {\n    throw err;\n  }\n}","preventionTips":["Assert replacement.metadata.name equals the target name in your build pipeline before shipping hot-swaps","Do renames explicitly (unregister + register) and update dependents' declarations","Keep plugin identity stable across versions; reserve name changes for coordinated upgrades"],"tags":["name-mismatch","hot-reload","plugin-registry","typescript"],"backgroundTag":"plugin-name-mismatch","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}