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.

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@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/db60296e97793a90. Report an issue: GitHub.

Appendix: source

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

      throw new ToolGatewayHttpError(
        401,
        "Tool gateway session is expired or invalid",
        "session_invalid",
      );
    }

    if (row.revokedAt) {
      await writeSessionAuthFailure(row, "session_revoked");
      throw new ToolGatewayHttpError(
        401,
        "Tool gateway session is expired or invalid",
        "session_revoked",
      );
    }

    if (row.expiresAt.getTime() <= Date.now()) {
      await writeSessionAuthFailure(row, "session_expired");
      throw new ToolGatewayHttpError(
        401,
        "Tool gateway session is expired or invalid",
        "session_expired",
      );
    }

    await assertSessionRunIsActive(row);

    const now = new Date();
    await db
      .update(toolGatewaySessions)
      .set({ lastUsedAt: now, updatedAt: now })
      .where(eq(toolGatewaySessions.id, row.id));

    const session = gatewaySessionFromRow({
      ...row,
      lastUsedAt: now,
      updatedAt: now,

View on GitHub (pinned to 3f1d897a7c)