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.

Source

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

          tool,
        }));
        const testDecision =
          decision.decision === "require_approval"
            ? "ask_first"
            : decision.allowed
              ? "allowed"
              : "off";
        return {
          toolName: tool.upstreamToolName ?? tool.name,
          gatewayToolName: tool.name,
          displayName: tool.displayName,
          risk: tool.risk,
          decision: testDecision,
          reasonCode: decision.reasonCode,
          matchedPolicyIds: decision.matchedPolicyIds,
          effectiveProfileIds: decision.effectiveProfileIds,
        };
      }));
      const lastChange = await summarizeAccessLastChange({
        companyId: input.companyId,
        connectionId: input.connectionId,
        agentId: input.agentId,
        policyIds: [...new Set(decisions.flatMap((decision) => decision.matchedPolicyIds))],
        profileIds: [...new Set(decisions.flatMap((decision) => decision.effectiveProfileIds))],
      });
      return {
        connectionId: input.connectionId,
        toolCount: decisions.length,
        allowedCount: decisions.filter((decision) => decision.decision === "allowed").length,
        askFirstCount: decisions.filter((decision) => decision.decision === "ask_first").length,
        offCount: decisions.filter((decision) => decision.decision === "off").length,
        lastChangedAt: lastChange.lastChangedAt,
        lastChangedByAgentId: lastChange.lastChangedByAgentId,
        lastChangedByName: lastChange.lastChangedByName,
        tools: decisions.map(({ effectiveProfileIds: _effectiveProfileIds, ...tool }) => tool),
      };

View on GitHub (pinned to 01ad858492)

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@01ad858492 (2026-08-18). Data as JSON: /api/errors/e8a8c01b78a86bc2. Report an issue: GitHub.