Tencent/WeKnora · error

failed to create SSE client: %w

Error message

failed to create SSE client: %w

What it means

NewMCPClient wraps any error returned by mark3labs NewSSEMCPClient or NewOAuthSSEClient with 'failed to create SSE client'. The constructor itself rarely fails — it mainly fails on URL parsing/invalid URL schemes, since the SSRF-safe HTTP client and headers are built beforehand. The underlying cause is always in the wrapped error.

Source

Thrown at internal/mcp/client.go:203

	var mcpClient *client.Client
	switch config.Service.TransportType {
	case types.MCPTransportSSE:
		if config.Service.URL == nil || *config.Service.URL == "" {
			return nil, fmt.Errorf("URL is required for SSE transport")
		}
		if useOAuth {
			mcpClient, err = client.NewOAuthSSEClient(*config.Service.URL, oauthConfig,
				transport.WithHTTPClient(httpClient),
				transport.WithHeaders(headers),
			)
		} else {
			mcpClient, err = client.NewSSEMCPClient(*config.Service.URL,
				client.WithHTTPClient(httpClient),
				client.WithHeaders(headers),
			)
		}
		if err != nil {
			return nil, fmt.Errorf("failed to create SSE client: %w", err)
		}
	case types.MCPTransportHTTPStreamable:
		if config.Service.URL == nil || *config.Service.URL == "" {
			return nil, fmt.Errorf("URL is required for HTTP Streamable transport")
		}
		if useOAuth {
			mcpClient, err = client.NewOAuthStreamableHttpClient(*config.Service.URL, oauthConfig,
				transport.WithHTTPBasicClient(httpClient),
				transport.WithHTTPHeaders(headers),
			)
		} else {
			// For HTTP streamable, we need to use transport options
			mcpClient, err = client.NewStreamableHttpClient(*config.Service.URL,
				transport.WithHTTPBasicClient(httpClient),
				transport.WithHTTPHeaders(headers),
			)
		}
		if err != nil {

View on GitHub (pinned to 988cbb0330)

Solutions

1. Inspect the wrapped %w cause printed after 'failed to create SSE client:' — it names the actual failure
2. Verify config.Service.URL parses with url.Parse and has an http/https scheme before calling NewMCPClient
3. Fix the stored service URL (must be absolute, e.g. https://host/sse)
4. If OAuth, confirm the OAuthConfig (client id/secret, token store) is well-formed before constructing

Example fix

// before
mcpClient, err = client.NewSSEMCPClient("example.com/sse", ...)
// after
u, perr := url.Parse(cfg.URL)
if perr != nil || (u.Scheme != "http" && u.Scheme != "https") {
    return nil, fmt.Errorf("invalid SSE service URL %q", cfg.URL)
}
mcpClient, err = client.NewSSEMCPClient(cfg.URL, ...)

func validSSEURL(raw *string) bool {
    if raw == nil || *raw == "" { return false }
    u, err := url.Parse(*raw)
    return err == nil && (u.Scheme == "http" || u.Scheme == "https") && u.Host != ""
}
// call before NewMCPClient when TransportType == MCPTransportSSE

func asCreateSSEClientErr(err error) (urlParseErr error, ok bool) {
    if err == nil || !strings.Contains(err.Error(), "failed to create SSE client") { return nil, false }
    return errors.Unwrap(err), true
}

mcpClient, err := NewMCPClient(cfg)
if err != nil {
    var cause error
    if strings.Contains(err.Error(), "failed to create SSE client") { cause = errors.Unwrap(err) }
    return fmt.Errorf("SSE client config invalid: %v", cause)
}

When it happens

Trigger: NewMCPClient called with config.Service.TransportType == types.MCPTransportSSE and a service URL that the mark3labs client package rejects when parsing (e.g. malformed URL, missing scheme, unsupported scheme). Also fires when NewOAuthSSEClient rejects the URL or OAuth config.

Common situations: Admin saved an MCP service URL like 'example.com/sse' without https://; URL contains spaces or invalid characters; stored URL corrupted by migration; OAuth-registered service passing an invalid redirect/base URL into the OAuth SSE client.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• failed to create HTTP streamable client: %w
• failed to start client: %w
• invalid URL: %w
• URL is required for SSE transport
• URL is required for HTTP Streamable transport

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