paperclipai/paperclip · error · ToolGatewayHttpError

session_expired

session_expired

Error message

Tool gateway session is expired or invalid

What it means

Sentinel 401 for an unrecognized gateway session token: the token hash matched no active session row. The failure is recorded for the candidate session (when derivable) as session_invalid so operators can audit invalid-token attempts; clients should obtain a fresh session rather than retry the same token.

Source

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

            ? input.details.gatewayTokenId
            : null,
        gatewayPublicId: typeof input.details.gatewayPublicId === "string" ? input.details.gatewayPublicId : null,
        clientName: typeof input.details.clientName === "string" ? input.details.clientName : null,
        correlationId: typeof input.details.correlationId === "string" ? input.details.correlationId : null,
        connectionId: typeof input.details.connectionId === "string" ? input.details.connectionId : null,
        catalogEntryId: typeof input.details.catalogEntryId === "string" ? input.details.catalogEntryId : null,
        actorType: input.actorType ?? input.session?.actorType ?? (input.agentId ? "agent" : "system"),
        actorId: input.actorId ?? input.session?.actorId ?? input.agentId ?? input.session?.gatewayTokenId ?? input.companyId,
        action: dedicatedAuditAction,
        outcome: dedicatedOutcome,
        reasonCode: typeof input.details.reasonCode === "string" ? input.details.reasonCode : null,
        details: {
          source: input.action,
          agentId: input.agentId,
          issueId: input.issueId,
          projectId: input.session?.projectId ?? null,
          runId: input.runId,
          gatewaySessionId: input.session?.id ?? null,
          gatewayId: input.session?.gatewayId ?? null,
          gatewayPublicId: input.session?.gatewayPublicId ?? null,
          gatewayName: input.session?.gatewayName ?? null,
          gatewayTokenId: input.session?.gatewayTokenId ?? null,
          ...input.details,
        },
      });
    } catch (error) {
      await recordToolRuntimeAuditWriteFailure(db, input.companyId);
      throw error;
    }

    const entityType = input.issueId ? "issue" : input.session?.gatewayId ? "tool_mcp_gateway" : "agent";
    const entityId = input.issueId ?? input.session?.gatewayId ?? input.agentId ?? input.companyId;
    await logActivity(db, {
      companyId: input.companyId,
      actorType: input.actorType ?? input.session?.actorType ?? (input.agentId ? "agent" : "system"),
      actorId: input.actorId ?? input.session?.actorId ?? input.agentId ?? input.session?.gatewayTokenId ?? input.companyId,

View on GitHub (pinned to 5716fe907e)

Solutions

1. Re-establish the tool gateway session (re-authenticate); the session token expired or is invalid.

When it happens

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

Common situations: See trigger scenarios.

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