paperclipai/paperclip · error

Tool "${namespacedName}" is not registered. The plugin may n

Error message

Tool "${namespacedName}" is not registered. The plugin may not be installed or its worker may not be running.

What it means

Registration guard in executeTool: the namespaced name parses but no tool is registered under it — the plugin is not installed or its worker never registered the tool. The missing tool registration is at fault.

Source

Thrown at server/src/services/plugin-tool-registry.ts:402

    async executeTool(
      namespacedName: string,
      parameters: unknown,
      runContext: ToolRunContext,
    ): Promise<ToolExecutionResult> {
      // 1. Resolve the namespaced name
      const parsed = parseName(namespacedName);
      if (!parsed) {
        throw new Error(
          `Invalid tool name "${namespacedName}". Expected format: "<pluginId>${TOOL_NAMESPACE_SEPARATOR}<toolName>"`,
        );
      }

      const { pluginId, toolName } = parsed;

      // 2. Verify the tool is registered
      const tool = byNamespace.get(namespacedName);
      if (!tool) {
        throw new Error(
          `Tool "${namespacedName}" is not registered. ` +
          `The plugin may not be installed or its worker may not be running.`,
        );
      }

      // 3. Verify the worker manager is available
      if (!workerManager) {
        throw new Error(
          `Cannot execute tool "${namespacedName}" — no worker manager configured. ` +
          `Tool execution requires a PluginWorkerManager.`,
        );
      }

      // 4. Verify the plugin worker is running (use DB UUID for worker lookup)
      const dbId = tool.pluginDbId;
      if (!workerManager.isRunning(dbId)) {
        throw new Error(
          `Cannot execute tool "${namespacedName}" — ` +

View on GitHub (pinned to 120ae5428f)

Solutions

1. Ensure the plugin is installed and its worker is running so its tools are registered; list registered tools to confirm the name.

When it happens

Trigger: Thrown at server/src/services/plugin-tool-registry.ts:402 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/c24fa24d3c930424. Report an issue: GitHub.