paperclipai/paperclip · error · ToolGatewayHttpError

session_invalid

session_invalid

Error message

Tool gateway session is expired or invalid

What it means

401 sentinel thrown after writeSessionAuthFailure logged a session_run_inactive event: the gateway session token itself is well-formed, but the run it authenticates for is no longer active, so the session is treated as expired/invalid and the client must re-authenticate against a new run.

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:1264 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/74753f7f35cfe27d. Report an issue: GitHub.

Appendix: source

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

        401,
        "Tool gateway session is expired or invalid",
        "session_run_inactive",
      );
    }
  }

  async function getActiveSession(
    sessionToken: string,
    namedGatewayProtocol?: {
      gatewayId?: string | null;
      gatewayPublicId?: string | null;
      protocolMethod: McpGatewayProtocolMethod;
      callerHeaders?: Record<string, string | string[] | undefined>;
    },
  ): Promise<ToolGatewaySession> {
    const token = sessionToken.trim();
    if (!token) {
      throw new ToolGatewayHttpError(
        401,
        "Tool gateway session is expired or invalid",
        "session_invalid",
      );
    }
    if (namedGatewayTokenId(token)) {
      return namedGatewaySessionFromBearer({
        gatewayId: namedGatewayProtocol?.gatewayId ?? null,
        gatewayPublicId: namedGatewayProtocol?.gatewayPublicId ?? null,
        bearerToken: token,
        protocolMethod: namedGatewayProtocol?.protocolMethod ?? "tools/call",
        callerHeaders: namedGatewayProtocol?.callerHeaders,
      });
    }

    const tokenHash = hashGatewayToken(token);
    const [row] = await db
      .select()

View on GitHub (pinned to 3f1d897a7c)