Tencent/WeKnora · error

failed to initialize: %w

Error message

failed to initialize: %w

What it means

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.

Source

Thrown at internal/mcp/client.go:398

		Params: mcp.InitializeParams{
			ProtocolVersion: mcp.LATEST_PROTOCOL_VERSION,
			Capabilities:    mcp.ClientCapabilities{},
			ClientInfo: mcp.Implementation{
				Name:    "WeKnora",
				Version: "1.0.0",
			},
		},
	}

	result, err := oauthCall(ctx, c, func() (*mcp.InitializeResult, error) {
		return c.client.Initialize(ctx, req)
	})
	if err != nil {
		c.checkErrorAndDisconnectIfNeeded(err)
		if oerr := asOAuthRequired(err); oerr != nil {
			return nil, oerr
		}
		return nil, fmt.Errorf("failed to initialize: %w", err)
	}

	c.initialized = true

	return &InitializeResult{
		ProtocolVersion: result.ProtocolVersion,
		ServerInfo: ServerInfo{
			Name:        result.ServerInfo.Name,
			Version:     result.ServerInfo.Version,
			Title:       result.ServerInfo.Title,
			Description: result.ServerInfo.Description,
		},
	}, nil
}

// ListTools retrieves the list of available tools
func (c *mcpGoClient) ListTools(ctx context.Context) ([]*types.MCPTool, error) {
	if !c.initialized {

View on GitHub (pinned to 988cbb0330)

Solutions

1. Confirm the URL points at the MCP endpoint and returns a proper MCP initialize response, not HTML
2. Check server and client MCP SDK/protocol versions are compatible
3. Re-run Connect then Initialize — a dropped session needs reconnection (checkErrorAndDisconnectIfNeeded may have already flagged it)
4. If 401/403, verify auth headers via service Headers/AuthConfig or complete the OAuth flow

Example fix

// before
url := "https://mcp.example.com/" // web UI, not MCP endpoint
// after
url := "https://mcp.example.com/mcp" // actual MCP streamable endpoint
if err := c.Connect(ctx); err != nil { return err }
res, err := c.Initialize(ctx)

func ensureConnectedThenInit(ctx context.Context, c MCPClient) (*InitializeResult, error) {
    if err := c.Connect(ctx); err != nil { return nil, err }
    return c.Initialize(ctx)
}

func isInitializeFailure(err error) bool {
    return err != nil && strings.Contains(err.Error(), "failed to initialize")
}

res, err := c.Initialize(ctx)
if err != nil {
    if asOAuthRequired(err) != nil { return handleReauth(err) }
    if isInitializeFailure(err) {
        // session likely dropped: full reconnect + retry once
        _ = c.Disconnect()
        if rerr := reconnectAndInit(ctx, c); rerr == nil { return c.Initialize(ctx) }
    }
    return nil, err
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• %s: %w
• failed to create SSE client: %w
• URL is required for HTTP Streamable transport
• failed to create HTTP streamable client: %w
• stdio transport is disabled for security reasons; please use

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/b0e26225dac7f6bb. Report an issue: GitHub.