paperclipai/paperclip · error

Plugin tool dispatch is not enabled

Error message

Plugin tool dispatch is not enabled

What it means

Returned as HTTP 501 by GET /api/plugins/tools (server/src/routes/plugins.ts:954) when the server was constructed without plugin tool dependencies (toolDeps) — i.e. the tool dispatcher/plugin worker subsystem is not wired into this deployment. 501 Not Implemented signals the endpoint exists but the feature is intentionally unavailable, not a client error.

Source

Thrown at server/src/routes/plugins.ts:969

  // Tool discovery and execution routes
  // ===========================================================================

  /**
   * GET /api/plugins/tools
   *
   * List all available plugin-contributed tools in an agent-friendly format.
   *
   * Query params:
   * - `pluginId` (optional): Filter to tools from a specific plugin
   *
   * Response: `AgentToolDescriptor[]`
   * Errors: 501 if tool dispatcher is not configured
   */
  router.get("/plugins/tools", async (req, res) => {
    assertBoardOrAgent(req);

    if (!toolDeps) {
      res.status(501).json({ error: "Plugin tool dispatch is not enabled" });
      return;
    }

    const pluginId = req.query.pluginId as string | undefined;
    if (req.actor.type === "agent" && toolGatewayDeps) {
      if (!req.actor.companyId || !req.actor.agentId) {
        res.status(401).json({ error: "Agent identity is required" });
        return;
      }
      const tools = await toolGatewayDeps.toolGateway.listPluginToolsForAgent({
        companyId: req.actor.companyId,
        agentId: req.actor.agentId,
      });
      res.json(pluginId ? tools.filter((tool) => tool.pluginId === pluginId || tool.name.startsWith(`${pluginId}:`)) : tools);
      return;
    }

    const filter = pluginId ? { pluginId } : undefined;

View on GitHub (pinned to a7e689b3c3)

Solutions

1. If tools should be available, start/configure the server with plugin tool dispatch enabled so toolDeps is provided to the plugins router
2. Verify you are pointed at the right server version (the endpoint and its wiring must both exist)
3. Clients should treat 501 as 'feature absent' and degrade gracefully (hide plugin tool UI) rather than retry

async function pluginToolsAvailable(): Promise<boolean> {
  const res = await fetch("/api/plugins/tools");
  return res.status !== 501;
}

const res = await fetch("/api/plugins/tools");
if (res.status === 501) {
  // Tool dispatch not configured on this server — hide plugin tools UI, do not retry
}

When it happens

Trigger: GET /api/plugins/tools (with or without ?pluginId=) against a server started with plugin tool dispatch disabled or not configured. Any board or agent request hits the same guard before auth-specific branches run.

Common situations: Minimal/test server builds that omit the plugin worker; deployments that deliberately disable plugin tool execution; version skew where a newer UI/CLI calls the endpoint on an older server that never wired toolDeps.

Related errors

• devUiUrl must use http or https protocol
• devUiUrl must target localhost
• Agent identity is required
• Request body is required
• "tool" is required and must be a string

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