{"record":{"id":"9d8dabf01178d5e6","repo":"microsoft/autogen","slug":"failed-to-create-websocket-connection","errorCode":null,"errorMessage":"Failed to create WebSocket connection","messagePattern":"Failed to create WebSocket connection","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-studio/frontend/src/components/views/teambuilder/builder/component-editor/fields/workbench/useMcpWebSocket.ts","lineNumber":161,"sourceCode":"            errorText || \"Failed to create WebSocket connection\"\n          }`\n        );\n      }\n\n      let connectionData;\n      try {\n        const responseText = await response.text();\n        console.log(\"Raw response:\", responseText);\n        connectionData = JSON.parse(responseText);\n      } catch (jsonError) {\n        console.error(\"JSON parse error:\", jsonError);\n        throw new Error(\n          `Invalid JSON response from server. Check if the MCP route is properly configured.`\n        );\n      }\n\n      if (!connectionData.status) {\n        throw new Error(\n          connectionData.message || \"Failed to create WebSocket connection\"\n        );\n      }\n\n      const { session_id, websocket_url } = connectionData;\n      const wsUrl = `${getWebSocketUrl()}${websocket_url}`;\n\n      // Create WebSocket connection\n      const ws = new WebSocket(wsUrl);\n      wsRef.current = ws;\n\n      ws.onopen = () => {\n        console.log(`MCP WebSocket connected to session ${session_id}`);\n        setState((prev) => ({\n          ...prev,\n          connected: true,\n          connecting: false,\n          sessionId: session_id,","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-studio/frontend/src/components/views/teambuilder/builder/component-editor/fields/workbench/useMcpWebSocket.ts#L143-L179","documentation":"Thrown by useMcpWebSocket when the MCP initiation endpoint returns valid JSON with status falsy and no message field. It means the backend deliberately reported a failed session creation but did not include a reason, so the generic message is used. Occurs after the JSON parse succeeded, before the WebSocket is constructed.","triggerScenarios":"POST succeeds (HTTP 200, valid JSON) but the backend response is {status: false} or {status: null} with no message — e.g. the MCP server process failed to start or validation of server_params failed silently server-side.","commonSituations":"MCP server executable not installed on the backend host; server_params schema accepted but semantically invalid; backend swallowed the underlying exception and returned status:false without message.","solutions":["Inspect the raw response body in the Network tab to confirm message is truly absent.","Check backend logs — the reason for status:false is usually logged even when omitted from the response.","Verify the MCP server command in server_params runs on the backend host with the same user/env.","Patch the backend to include the failure reason in the message field so the UI shows the real cause."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"interface McpSessionResponse { status?: boolean; message?: string; session_id?: string; websocket_url?: string; }\nconst isMcpSessionResponse = (d: unknown): d is McpSessionResponse =>\n  typeof d === 'object' && d !== null && 'session_id' in d && 'websocket_url' in d;","tryCatchPattern":"try {\n  await connectMcp(serverParams);\n} catch (e) {\n  if (e instanceof Error && e.message === 'Failed to create WebSocket connection') {\n    // Backend returned status:false with no reason: check server logs\n    showServerError('MCP session rejected; see backend logs for the reason.');\n  }\n}","preventionTips":["Make the backend always include a message when returning status:false.","Log session-creation failures server-side with the exception detail.","Validate server_params (command exists, port free) before spawning the session."],"tags":["mcp","websocket","backend","error-handling"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}