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.

Solutions

1. The remote MCP call timed out. Retry, increase the timeout if configurable, or check the remote server's latency/load.

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

Appendix: source

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

      }
      if (error instanceof ToolGatewayHttpError) {
        throw new ToolGatewayHttpError(
          error.status,
          error.message,
          error.reasonCode,
          {
            ...error.details,
            execution: error.details.execution ?? execution,
          },
        );
      }
      if (error instanceof Error && error.name === "AbortError") {
        await markRemoteConnectionHealth(
          connection,
          "error",
          "Remote MCP tool call timed out.",
        );
        throw new ToolGatewayHttpError(
          504,
          "Remote MCP tool call timed out",
          "tool_timeout",
          {
            connectionId: connection.id,
            catalogEntryId: entry.id,
            execution,
          },
        );
      }
      await markRemoteConnectionHealth(
        connection,
        "error",
        "Remote MCP tool call failed.",
      );
      throw new ToolGatewayHttpError(
        502,
        "Remote MCP tool call failed",

View on GitHub (pinned to 3f1d897a7c)