What causes "failed to create Cassandra session: %w" in googleapis/mcp-toolbox?

Verify hosts and port (default 9042) are correct and reachable.

failed to create Cassandra session

Error message

failed to create Cassandra session: %w

What it means

cluster.CreateSession() in initCassandraSession failed to establish a session to the Cassandra cluster. This is the underlying connection step; the gocql error is wrapped with %w for direct unwrapping with errors.Is/As.

Solutions

Verify hosts and port (default 9042) are correct and reachable.
Confirm credentials are valid (cqlsh login works).
Check ProtoVersion compatibility with the server.
Inspect TLS/SSL settings on the cluster config.
Use errors.Unwrap to get the root gocql error.

Example fix

// before
cluster.ProtoVersion = 4 // server only supports 3
// after
cluster.ProtoVersion = 3

Defensive patterns

Strategy: retry

Validate before calling

conn, err := net.DialTimeout("tcp", host+":9042", 3*time.Second)
if err != nil { return fmt.Errorf("cassandra unreachable: %w", err) }
conn.Close()

Try / catch

_, err := cfg.Initialize(ctx, tracer)
if err != nil {
    // retry with backoff; unwrap for gocql root cause
    return fmt.Errorf("session failed: %w", errors.Unwrap(err))
}

Prevention

Verify host/port reachability before init.
Confirm credentials with cqlsh first.
Keep ProtoVersion consistent with server version.

When it happens

Trigger: Calling Initialize when gocql cannot dial any host: connection refused, TLS handshake failure, authentication rejected, or protocol version mismatch.

Common situations: Cluster down, wrong port, wrong credentials, TLS misconfiguration, unsupported ProtoVersion, DNS resolution failures.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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

Appendix: source

Thrown at internal/sources/cassandra/cassandra.go:160

			Username: c.Username,
			Password: c.Password,
		}
	}

	// Configure SSL options if any are specified
	if c.CAPath != "" || c.CertPath != "" || c.KeyPath != "" || c.EnableHostVerification {
		cluster.SslOpts = &gocql.SslOptions{
			CaPath:                 c.CAPath,
			CertPath:               c.CertPath,
			KeyPath:                c.KeyPath,
			EnableHostVerification: c.EnableHostVerification,
		}
	}

	// Create session
	session, err := cluster.CreateSession()
	if err != nil {
		return nil, fmt.Errorf("failed to create Cassandra session: %w", err)
	}
	return session, nil
}

View on GitHub (pinned to 8cc6e09de2)