paperclipai/paperclip · error

Tool gateway service is not configured

Error message

Tool gateway service is not configured

What it means

Sentinel guard in the tool-access routes: the test-agent access endpoint requires the toolGateway service, and when options.toolGateway was not injected into the router the endpoint responds 501 'Tool gateway service is not configured'. It signals a deployment/configuration gap, not a client error — the server build lacks the gateway integration.

Source

Thrown at server/src/routes/tool-access.ts:2027

        continue;
      }
      candidates.push({
        id: agent.id,
        name: agent.name,
        role: agent.role,
        title: agent.title,
        status: agent.status,
        orgDepth: orgDepthByAgentId.get(agent.id) ?? 0,
      });
    }
    candidates.sort((a, b) => a.orgDepth - b.orgDepth || a.name.localeCompare(b.name));
    res.json({ agents: candidates });
  });

  router.get("/tool-connections/:connectionId/test-agents/:agentId/access", async (req, res) => {
    assertBoard(req);
    if (!options.toolGateway) {
      res.status(501).json({ error: "Tool gateway service is not configured" });
      return;
    }
    const connection = await getAccessibleResource(req, res, svc.getConnection(req.params.connectionId as string), "Tool connection not found");
    if (!connection) return;
    await assertBoardAnyToolPermission(req, connection.companyId, ["tools:use", "tools:manage_connections"]);
    const agentId = req.params.agentId as string;
    await assertCanTestAsAgent(req, connection.companyId, agentId);
    const accessSummary = await options.toolGateway.summarizeConnectionAccessForAgent({
      companyId: connection.companyId,
      connectionId: connection.id,
      agentId,
    });
    res.json({ access: accessSummary });
  });

  router.post("/tool-connections/:connectionId/test-calls", validate(toolConnectionTestCallSchema), async (req, res) => {
    assertBoard(req);
    if (!options.toolGateway) {

View on GitHub (pinned to 01ad858492)

Solutions

1. Deploy/configure the server with the tool gateway service enabled so options.toolGateway is injected.
2. Verify the server bootstrap passes toolGateway into toolAccessRoutes options.
3. Treat the 501 as a feature-unavailable signal in clients and hide/disable the access-test UI.

When it happens

Trigger: Thrown at server/src/routes/tool-access.ts:1848 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-02). Data as JSON: /api/errors/97bdc06683a33793. Report an issue: GitHub.