paperclipai/paperclip · error · ToolGatewayHttpError

session_scope_mismatch

session_scope_mismatch

Error message

Tool gateway session is outside the authenticated agent scope

What it means

Agent-scope check on session management: the session exists in the company, but an agent-scoped caller's agentId (and optional runId) do not cover the session being modified. The 403 ensures an agent key can only revoke/inspect sessions belonging to its own scope, not other agents' sessions.

Solutions

1. Use a gateway session that belongs to the authenticated agent; sessions of other agents are out of scope.

When it happens

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

Common situations: See trigger scenarios.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

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

Appendix: source

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

          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
        .update(toolGatewaySessions)
        .set({ revokedAt: now, updatedAt: now })
        .where(
          and(
            eq(toolGatewaySessions.companyId, input.companyId),
            eq(toolGatewaySessions.id, input.sessionId),
          ),
        )
        .returning();
      const sessionView = gatewaySessionFromRow(session!);
      await writeAudit({

View on GitHub (pinned to 3f1d897a7c)