microsoft/autogen · error · Error

HTTP ${response.status}: ${errorText || "Failed to create We

Error message

HTTP ${response.status}: ${errorText || "Failed to create WebSocket connection"}

What it means

Thrown by McpAPI.createWebSocketConnection when POST /mcp/ws/connect returns non-2xx. Unlike the JSON-based paths, this one reads the body as text and embeds both the status code and body text in the error, so the message here is a template literal pattern, not the literal thrown string. Failures include backend refusal to create the MCP session or transport errors during server connection.

Source

Thrown at python/packages/autogen-studio/frontend/src/components/views/mcp/api.ts:278

        return result.status;
      }
      return false;
    } catch (error) {
      return false;
    }
  }

  // WebSocket connection management
  async createWebSocketConnection(serverParams: McpServerParams): Promise<any> {
    const response = await fetch(`${this.getBaseUrl()}/mcp/ws/connect`, {
      method: "POST",
      headers: this.getHeaders(),
      body: JSON.stringify({ server_params: serverParams }),
    });

    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(
        `HTTP ${response.status}: ${
          errorText || "Failed to create WebSocket connection"
        }`
      );
    }

    try {
      const responseText = await response.text();
      return JSON.parse(responseText);
    } catch (jsonError) {
      throw new Error(
        `Invalid JSON response from server. Check if the MCP route is properly configured.`
      );
    }
  }
}

// WebSocket-based MCP functionality

View on GitHub (pinned to 027ecf0a37)

Solutions

Read the embedded status/body in the thrown message — 'HTTP 500: ...' text carries the backend's reason
Check backend logs at the moment of the call; spawn/connect failures are logged server-side with the command and stderr
Verify server_params against the backend's expected schema (command/args/env for stdio, url/headers for SSE)
Ensure the auth token is valid if status is 401/403
If behind a proxy, confirm POST /mcp/ws/connect is forwarded and not size/time limited

Defensive patterns

Strategy: try-catch

Validate before calling

null

Try / catch

try {
  const conn = await mcpAPI.createWebSocketConnection(serverParams);
  return conn;
} catch (e) {
  const msg = e instanceof Error ? e.message : String(e);
  if (msg.startsWith("HTTP 401") || msg.startsWith("HTTP 403")) await reauthenticate();
  throw e;
}

Prevention

Map the embedded 'HTTP <status>' prefix to user actions (401 → re-login, 500 → check backend logs)
Surface the full status+body string in diagnostics — it is the only client-side evidence
Test server_params with listTools first; if that works, ws/connect failures are transport-specific

When it happens

Trigger: POST {base}/mcp/ws/connect with server_params returning 4xx/5xx: backend cannot spawn/connect the MCP server (bad command, missing binary), server_params schema rejected, auth failure, or no WebSocket-capable transport available for the given server type.

Common situations: stdio server command not found in the backend container, SSE URL unreachable from backend, reverse proxy (nginx) blocking or timing out the connect endpoint, backend log shows the real spawn error while the browser only sees the HTTP status.

Related errors

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/9e6026f0b226e363. Report an issue: GitHub.