paperclipai/paperclip · error · Error

No tool handler registered for "${params.toolName}"

Error message

No tool handler registered for "${params.toolName}"

What it means

Dispatch guard in the worker RPC host (handleExecuteTool): the host requested tool execution for params.toolName, but no tool handler was registered under that name by the plugin. The manifest may advertise a tool the plugin never implemented, so execution fails fast at dispatch.

Source

Thrown at packages/plugins/sdk/src/worker-rpc-host.ts:1941

    });
  }

  function stringOrNull(value: unknown): string | null {
    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
  }

  function actorTypeOrSystem(value: unknown): PluginPerformActionActorContext["type"] {
    return value === "user" || value === "agent" || value === "system" ? value : "system";
  }

  function actionContextFromParams(params: PerformActionParams): PluginPerformActionContext {
    const rawActor = params.actorContext && typeof params.actorContext === "object"
      ? params.actorContext
      : null;
    const actor = Object.freeze({
      type: actorTypeOrSystem(rawActor?.type),
      userId: stringOrNull(rawActor?.userId),
      agentId: stringOrNull(rawActor?.agentId),
      runId: stringOrNull(rawActor?.runId),
      companyId: stringOrNull(rawActor?.companyId),
    });
    return Object.freeze({
      actor,
      companyId: actor.companyId,
    });
  }

  async function handlePerformAction(params: PerformActionParams): Promise<unknown> {
    const handler = actionHandlers.get(params.key);
    if (!handler) {
      throw new Error(`No action handler registered for key "${params.key}"`);
    }
    return handler(
      {
        ...params.params,
        ...(params.companyId === undefined ? {} : { companyId: params.companyId }),

View on GitHub (pinned to 01ad858492)

Solutions

1. Register a tool handler for the tool name, or call a registered tool.

When it happens

Trigger: Thrown at packages/plugins/sdk/src/worker-rpc-host.ts:1890 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/1a1db76b81ec8c0f. Report an issue: GitHub.