paperclipai/paperclip · error · ToolGatewayHttpError

session_not_found

session_not_found

Error message

Tool gateway session not found

What it means

Session revocation/management lookup: no toolGatewaySessions row exists for the supplied sessionId within the given company. The 404 fires on the company-scoped select before any revocation or mutation happens, covering deleted sessions and cross-company session ids.

Solutions

1. Verify the gateway session ID; it may have expired or been closed. Re-establish the session.

When it happens

Trigger: Thrown at server/src/services/tool-gateway.ts:6280 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/ad04d7c287466335. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/tool-gateway.ts:10815

        actorId?: string;
        agentId?: string | null;
        runId?: string | null;
      };
      agentScope?: { agentId: string; runId?: string | null } | null;
    }) {
      const now = input.revokedAt ?? new Date();
      const [existing] = await db
        .select()
        .from(toolGatewaySessions)
        .where(
          and(
            eq(toolGatewaySessions.companyId, input.companyId),
            eq(toolGatewaySessions.id, input.sessionId),
          ),
        )
        .limit(1);
      if (!existing) {
        throw new ToolGatewayHttpError(
          404,
          "Tool gateway session not found",
          "session_not_found",
        );
      }
      if (input.agentScope) {
        const runMatches = input.agentScope.runId
          ? existing.runId === input.agentScope.runId
          : true;
        if (existing.agentId !== input.agentScope.agentId || !runMatches) {
          throw new ToolGatewayHttpError(
            403,
            "Tool gateway session is outside the authenticated agent scope",
            "session_scope_mismatch",
          );
        }
      }
      const [session] = await db

View on GitHub (pinned to 3f1d897a7c)