t8y2/dbx · error

protocolversion must be between 3 and 5

Error message

protocolversion must be between 3 and 5

What it means

The 'protocolversion' (alias 'protoversion') URL parameter must parse as an integer between 3 and 5 inclusive, matching the Cassandra CQL protocol versions gocql supports. Any non-integer, or a version outside 3-5, produces this validation error.

Source

Thrown at agents/drivers/cassandra-go/config.go:184

		switch key {
		case "localdatacenter", "datacenter", "dc":
			config.localDatacenter = value
		case "requesttimeout", "timeout":
			duration, err := parseDurationOption(value)
			if err != nil {
				return fmt.Errorf("invalid requesttimeout: %w", err)
			}
			config.requestTimeout = duration
		case "connecttimeout", "logintimeout":
			duration, err := parseDurationOption(value)
			if err != nil {
				return fmt.Errorf("invalid connecttimeout: %w", err)
			}
			config.connectTimeout = duration
		case "protocolversion", "protoversion":
			version, err := strconv.Atoi(value)
			if err != nil || version < 3 || version > 5 {
				return fmt.Errorf("protocolversion must be between 3 and 5")
			}
			config.protocolVersion = version
		case "consistency":
			if _, err := gocql.ParseConsistencyWrapper(value); err != nil {
				return err
			}
			config.consistency = value
		case "serialconsistency":
			consistency, err := gocql.ParseConsistencyWrapper(value)
			if err != nil {
				return err
			}
			if consistency != gocql.Serial && consistency != gocql.LocalSerial {
				return fmt.Errorf("serialconsistency must be SERIAL or LOCAL_SERIAL")
			}
			config.serialConsistency = value
		case "numconns", "connectionsperhost":
			count, err := strconv.Atoi(value)

View on GitHub (pinned to c0390bff16)

Solutions

1. Set protocolversion to 3, 4, or 5 to match the cluster's CQL native protocol version.
2. Remove protocolversion so the driver auto-negotiates the protocol with the server.
3. If you meant the CQL spec version, use the cqlversion parameter instead (e.g. cqlversion=3.4.4).
4. Check the server's protocol version (cqlsh or nodetool) and align the value.

Example fix

// before
cassandra://host:9042?protocolversion=4.0
// after
cassandra://host:9042?protocolversion=4

func validProtocolVersion(v string) error {
	n, err := strconv.Atoi(v)
	if err != nil || n < 3 || n > 5 {
		return fmt.Errorf("protocolversion must be an integer 3-5, got %q", v)
	}
	return nil
}

cfg, err := parseCassandraConfig(dsn)
if err != nil {
	if strings.Contains(err.Error(), "protocolversion must be between 3 and 5") {
		return fmt.Errorf("fix protocolversion (integer 3-5) or remove it to auto-negotiate: %w", err)
	}
	return err
}

When it happens

Trigger: protocolversion=2 (too old), protocolversion=4.0 (non-integer), protocolversion=v4, or protocolversion=6+ in a cassandra:// URL passed to parseCassandraConfig.

Common situations: Pointing a modern driver at a very old Cassandra 1.2 cluster (protocol v2), copying '4.0' from CQL version notation (confusing protocol version with CQL version), or upgrading a cluster and over-guessing the protocol version.

Related errors

• serialconsistency must be SERIAL or LOCAL_SERIAL
• numconns must be between 1 and 32
• pagesize must be positive
• retries must be between 0 and 1000
• unsupported Cassandra URL parameter: %s

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/1168a949e77944c3. Report an issue: GitHub.