paperclipai/paperclip · error · ToolGatewayHttpError

run_context_mismatch

run_context_mismatch

Error message

Supplied run context does not match stored heartbeat context

What it means

Guard in the tool gateway run-context check: the companyId/agentId supplied with the gateway request do not match the heartbeat run stored for that runId, or the run is not in an active gateway status. It fires when a client reuses a runId belonging to a different company/agent or after the run finished, protecting against cross-tenant or stale-session tool execution.

Source

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

          isWrite: catalogEntry.isWrite,
          isDestructive: catalogEntry.isDestructive,
        },
        onDemandTools,
      };
      return {
        name: gatewayToolName,
        displayName: catalogEntry.title ?? catalogEntry.toolName,
        description: catalogEntry.description ?? `Connected MCP tool ${catalogEntry.toolName} from ${connection.name}.`,
        parametersSchema: inputSchema,
        pluginId: `mcp:${applicationKey ?? application.id}`,
        providerType: connection.transport === "local_stdio" ? "mcp_local_stdio" : "mcp_remote_http",
        risk,
        applicationId: application.id,
        applicationKey,
        applicationDisplayName: application.name,
        connectionId: connection.id,
        catalogEntryId: catalogEntry.id,
        upstreamToolName: catalogEntry.toolName,
        providerMetadata,
      };
    });
  }

  async function connectedMcpToolsForConnection(companyId: string, connectionId: string): Promise<ToolGatewayDescriptor[]> {
    return (await connectedMcpToolsForCompany(companyId))
      .filter((tool) => tool.connectionId === connectionId);
  }

  async function assertAgentInCompany(companyId: string, agentId: string): Promise<void> {
    const [agent] = await db
      .select({
        companyId: agents.companyId,
      })
      .from(agents)
      .where(eq(agents.id, agentId))
      .limit(1);

View on GitHub (pinned to 01ad858492)

Solutions

1. Supply the same run context (runId, etc.) that was stored at heartbeat/session creation; do not mix contexts from different runs.

When it happens

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

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/43e80e5fcc829db3. Report an issue: GitHub.