paperclipai/paperclip · error · ToolGatewayHttpError
tool_timeout
tool_timeout
Error message
Remote MCP tool call timed out
What it means
The remote MCP tools/call fetch aborted via AbortError, meaning the upstream server exceeded the configured timeout. Connection health is marked error and a 504/gateway-timeout style failure is returned; the call itself may or may not have executed remotely, so blind retry of non-idempotent tools is unsafe.
Source
Thrown at server/src/services/tool-gateway.ts:3159
status: "pending",
continuationPolicy: "wake_assignee",
requestedResolverPolicy: "human_only",
effectiveResolverPolicy: "human_only",
resolverPolicyProvenance: "explicit",
effectiveResolverPolicySource: "requested",
idempotencyKey,
sourceRunId: session.runId,
title: `Delegate your ${connection.name}`,
summary: "An explicit standing delegation is required for this autonomous run.",
createdByAgentId: session.agentId,
addresseeUserId: userId,
payload,
});
}
async function resolveConnectionGrant(
session: ToolGatewaySession,
connection: typeof toolConnections.$inferSelect,
): Promise<typeof connectionGrants.$inferSelect> {
const [run] = session.runId
? await db.select({
responsibleUserId: heartbeatRuns.responsibleUserId,
invocationSource: heartbeatRuns.invocationSource,
}).from(heartbeatRuns).where(and(
eq(heartbeatRuns.id, session.runId),
eq(heartbeatRuns.companyId, session.companyId),
)).limit(1)
: [];
const actingUserId = run?.responsibleUserId ?? session.responsibleUserId ?? null;
const autonomous = run?.invocationSource === "automation" || run?.invocationSource === "timer";
const findUserGrant = async () => {
if (!actingUserId) return undefined;
const [membership] = await db.select({ id: companyMemberships.id }).from(companyMemberships).where(and(
eq(companyMemberships.companyId, connection.companyId),
eq(companyMemberships.principalType, "user"),
eq(companyMemberships.principalId, actingUserId),View on GitHub (pinned to 5716fe907e)
Solutions
- The remote MCP call timed out. Retry, increase the timeout if configurable, or check the remote server's latency/load.
Defensive patterns
Strategy: retry
When it happens
Trigger: Thrown at server/src/services/tool-gateway.ts:3159 when the library encounters an invalid state.
Common situations: See trigger scenarios.
Understand the failure class
- Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.
AI-assisted analysis of paperclipai/paperclip@5716fe907e (2026-08-18).
Data as JSON: /api/errors/20d15a25eea8ae45.
Report an issue: GitHub.