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

Confirm reachability: `cqlsh 9042` or `nc -zv 9042` from the toolbox host.

failed to create ScyllaDB session: %w

Error message

failed to create ScyllaDB session: %w

What it means

After building the gocql.ClusterConfig, initScyllaDBSession calls cluster.CreateSession(), which opens connections to the contact points (and performs host discovery). Any failure — unreachable hosts, auth rejection, keyspace not existing, protocol mismatch — is wrapped with this message. The wrapped error contains the driver's specific cause.

Source

Thrown at internal/sources/scylladb/scylladb.go:181

			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 ScyllaDB session: %w", err)
	}
	return session, nil
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

Confirm reachability: `cqlsh <host> 9042` or `nc -zv <host> 9042` from the toolbox host.
If the error mentions the keyspace, create it (`CREATE KEYSPACE ...`) or fix the `keyspace` field.
If authentication errors, verify username/password against the cluster's authenticator config.
Set `protoVersion` explicitly (e.g. 4 or 3) if protocol negotiation errors appear.
Ensure `hosts` entries include the correct port and that the CQL native transport is enabled.

Example fix

// before
sources:
  scylla:
    kind: scylladb
    hosts: ["localhost:9142"]
    keyspace: myKeySpace
// after (correct port and existing keyspace)
sources:
  scylla:
    kind: scylladb
    hosts: ["localhost:9042"]
    keyspace: my_keyspace

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
# Verify CQL native transport reachability before starting the toolbox
HOST=scylla; PORT=9042
nc -zv "$HOST" "$PORT" || { echo "$HOST:$PORT unreachable"; exit 1; }
# Confirm keyspace exists (via cqlsh)
cqlsh "$HOST" "$PORT" -e "DESCRIBE KEYSPACES" | grep -q my_keyspace \
  || { echo "keyspace missing"; exit 1; }

Prevention

Readiness-check the cluster (cqlsh ping equivalent) before launching the toolbox.
Verify keyspace names are created and case-correct (CQL lowercases unquoted identifiers).
Pin protoVersion to the value your server supports to avoid negotiation failures.
Keep hosts list to reachable contact points with the correct 9042 native port.

When it happens

Trigger: Config.Initialize → initScyllaDBSession → cluster.CreateSession() fails: no host reachable at hosts:port, handshake/auth rejected, `keyspace` does not exist, protoVersion unsupported, or TLS handshake fails.

Common situations: ScyllaDB container not started or wrong port (native transport 9042 not exposed); firewall between toolbox and cluster; keyspace name typo; authenticator PasswordAuthenticator with wrong credentials; ProtoVersion too high for the server.

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/37970144dceb9252. Report an issue: GitHub.