What causes "MCP initialize handshake failed" in Tencent/WeKnora?

Inspect the underlying wrapped error for the handshake failure cause (network, protocol version, auth)

MCP initialize handshake failed

Error message

MCP initialize handshake failed

What it means

Sentinel returned when the MCP initialize handshake with the server fails. It indicates the server did not complete or correctly answer the initialize request during connection setup, so the client remains unusable until a successful re-initialization.

Source

Thrown at internal/mcp/errors.go:16

package mcp

import "errors"

var (
	// ErrUnsupportedTransport is returned when transport type is not supported
	ErrUnsupportedTransport = errors.New("unsupported transport type")

	// ErrNotConnected is returned when operation requires connection but client is not connected
	ErrNotConnected = errors.New("client not connected")

	// ErrAlreadyConnected is returned when trying to connect an already connected client
	ErrAlreadyConnected = errors.New("client already connected")

	// ErrInitializeFailed is returned when MCP initialize handshake fails
	ErrInitializeFailed = errors.New("MCP initialize handshake failed")

	// ErrToolNotFound is returned when requested tool is not found
	ErrToolNotFound = errors.New("tool not found")

	// ErrResourceNotFound is returned when requested resource is not found
	ErrResourceNotFound = errors.New("resource not found")

	// ErrInvalidResponse is returned when server response is invalid
	ErrInvalidResponse = errors.New("invalid response from server")

	// ErrTimeout is returned when operation times out
	ErrTimeout = errors.New("operation timed out")

	// ErrConnectionClosed is returned when connection is closed unexpectedly
	ErrConnectionClosed = errors.New("connection closed")
)

View on GitHub (pinned to 988cbb0330)

Solutions

Inspect the underlying wrapped error for the handshake failure cause (network, protocol version, auth)
Retry the Connect/Initialize sequence; transient network errors often resolve on retry
Verify the MCP server is running the expected protocol version and is reachable
Check server logs for why the initialize request was rejected

Defensive patterns

Strategy: retry

When it happens

Trigger: Thrown at internal/mcp/errors.go:16 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

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