googleapis/mcp-toolbox · error

unable to connect successfully: %w

Error message

unable to connect successfully: %w

What it means

After building the pool, Initialize calls PingContext to verify connectivity. If the ping fails, the pool is closed and this error is returned, meaning the ClickHouse server could not be reached or authenticated.

Source

Thrown at internal/sources/clickhouse/clickhouse.go:75

	Password string `yaml:"password"`
	Protocol string `yaml:"protocol"`
	Secure   bool   `yaml:"secure"`
}

func (r Config) SourceConfigType() string {
	return SourceType
}

func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {
	pool, err := initClickHouseConnectionPool(ctx, tracer, r.Name, r.Host, r.Port, r.User, r.Password, r.Database, r.Protocol, r.Secure)
	if err != nil {
		return nil, fmt.Errorf("unable to create pool: %w", err)
	}

	err = pool.PingContext(ctx)
	if err != nil {
		pool.Close()
		return nil, fmt.Errorf("unable to connect successfully: %w", err)
	}

	s := &Source{
		Config: r,
		Pool:   pool,
	}
	return s, nil
}

var _ sources.Source = &Source{}

type Source struct {
	Config
	Pool *sql.DB
}

func (s *Source) IsReadOnly() bool {
	return false

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Check ClickHouse is running and reachable at host:port.
2. Validate user/password and that the database exists.
3. Match the secure flag to the server's TLS configuration.
4. Increase the context timeout if initialization races a slow startup.
5. Read the wrapped error for the driver's root cause.

Example fix

// before
r := clickhouse.Config{Host: "10.0.0.5", Port: "8123", Secure: false}
// after
r := clickhouse.Config{Host: "10.0.0.5", Port: "8443", Secure: true}

conn, err := net.DialTimeout("tcp", net.JoinHostPort(r.Host, r.Port), 3*time.Second)
if err != nil { return fmt.Errorf("clickhouse unreachable: %w", err) }
conn.Close()

src, err := cfg.Initialize(ctx, tracer)
if err != nil {
    if strings.Contains(err.Error(), "unable to connect successfully") {
        // transient: retry with backoff; else surface config error
        return retryOrSurface(err)
    }
    return err
}

When it happens

Trigger: Calling Initialize when pool.PingContext(ctx) fails: server unreachable, wrong credentials, database missing, TLS mismatch, or the context is cancelled/timed out.

Common situations: ClickHouse not running, wrong port, wrong user/password, database doesn't exist, secure=false against a TLS-only server, network egress blocked.

Related errors

• unable to connect successfully: %w
• unable to connect successfully: %w
• unable to connect successfully: %w
• unable to create pool: %w
• unable to execute query: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/74c9bb3eeb9ad95d. Report an issue: GitHub.