{"record":{"id":"b0e26225dac7f6bb","repo":"Tencent/WeKnora","slug":"failed-to-initialize-w","errorCode":null,"errorMessage":"failed to initialize: %w","messagePattern":"failed to initialize: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/mcp/client.go","lineNumber":398,"sourceCode":"\t\tParams: mcp.InitializeParams{\n\t\t\tProtocolVersion: mcp.LATEST_PROTOCOL_VERSION,\n\t\t\tCapabilities:    mcp.ClientCapabilities{},\n\t\t\tClientInfo: mcp.Implementation{\n\t\t\t\tName:    \"WeKnora\",\n\t\t\t\tVersion: \"1.0.0\",\n\t\t\t},\n\t\t},\n\t}\n\n\tresult, err := oauthCall(ctx, c, func() (*mcp.InitializeResult, error) {\n\t\treturn c.client.Initialize(ctx, req)\n\t})\n\tif err != nil {\n\t\tc.checkErrorAndDisconnectIfNeeded(err)\n\t\tif oerr := asOAuthRequired(err); oerr != nil {\n\t\t\treturn nil, oerr\n\t\t}\n\t\treturn nil, fmt.Errorf(\"failed to initialize: %w\", err)\n\t}\n\n\tc.initialized = true\n\n\treturn &InitializeResult{\n\t\tProtocolVersion: result.ProtocolVersion,\n\t\tServerInfo: ServerInfo{\n\t\t\tName:        result.ServerInfo.Name,\n\t\t\tVersion:     result.ServerInfo.Version,\n\t\t\tTitle:       result.ServerInfo.Title,\n\t\t\tDescription: result.ServerInfo.Description,\n\t\t},\n\t}, nil\n}\n\n// ListTools retrieves the list of available tools\nfunc (c *mcpGoClient) ListTools(ctx context.Context) ([]*types.MCPTool, error) {\n\tif !c.initialized {","sourceCodeStart":380,"sourceCodeEnd":416,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/mcp/client.go#L380-L416","documentation":"Initialize performs the MCP protocol handshake after Start. Errors from c.client.Initialize are wrapped with 'failed to initialize'. This means the transport connected but the protocol exchange failed: server not speaking MCP, protocol version mismatch, server-side panic, or the session dropped between Start and Initialize. OAuth-required errors are returned unwrapped.","triggerScenarios":"Connect succeeded, then Initialize(ctx) called and the server rejected/failed the initialize request: wrong endpoint (an HTML page instead of MCP), protocol version incompatibility, server crashed mid-handshake, session expired immediately.","commonSituations":"Pointing at a URL that serves a web UI instead of the MCP endpoint; server upgraded to an incompatible MCP protocol version; load balancer timing out long handshakes; server requires auth and returns 401 during initialize (non-OAuth path).","solutions":["Confirm the URL points at the MCP endpoint and returns a proper MCP initialize response, not HTML","Check server and client MCP SDK/protocol versions are compatible","Re-run Connect then Initialize — a dropped session needs reconnection (checkErrorAndDisconnectIfNeeded may have already flagged it)","If 401/403, verify auth headers via service Headers/AuthConfig or complete the OAuth flow"],"exampleFix":"// before\nurl := \"https://mcp.example.com/\" // web UI, not MCP endpoint\n// after\nurl := \"https://mcp.example.com/mcp\" // actual MCP streamable endpoint\nif err := c.Connect(ctx); err != nil { return err }\nres, err := c.Initialize(ctx)","handlingStrategy":"try-catch","validationCode":"func ensureConnectedThenInit(ctx context.Context, c MCPClient) (*InitializeResult, error) {\n    if err := c.Connect(ctx); err != nil { return nil, err }\n    return c.Initialize(ctx)\n}","typeGuard":"func isInitializeFailure(err error) bool {\n    return err != nil && strings.Contains(err.Error(), \"failed to initialize\")\n}","tryCatchPattern":"res, err := c.Initialize(ctx)\nif err != nil {\n    if asOAuthRequired(err) != nil { return handleReauth(err) }\n    if isInitializeFailure(err) {\n        // session likely dropped: full reconnect + retry once\n        _ = c.Disconnect()\n        if rerr := reconnectAndInit(ctx, c); rerr == nil { return c.Initialize(ctx) }\n    }\n    return nil, err\n}","preventionTips":["Point URLs at the real MCP endpoint path, not a web UI","Keep server and client MCP SDK versions aligned; pin protocol versions","Test initialize against each registered service after config changes"],"tags":["go","mcp","protocol","handshake"],"backgroundTag":"mcp-handshake-failed","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}