t8y2/dbx · error

numconns must be between 1 and 32

Error message

numconns must be between 1 and 32

What it means

The 'numconns' (alias 'connectionsperhost') URL parameter must parse as an integer between 1 and 32. Non-numeric values or counts outside that range are rejected with this error, since gocql requires at least one connection per host and the driver caps the pool at 32.

Source

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

			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)
			if err != nil || count < 1 || count > 32 {
				return fmt.Errorf("numconns must be between 1 and 32")
			}
			config.numConnections = count
		case "pagesize", "fetchsize":
			size, err := strconv.Atoi(value)
			if err != nil || size < 1 {
				return fmt.Errorf("pagesize must be positive")
			}
			config.pageSize = size
		case "cqlversion":
			config.cqlVersion = value
		case "ssl", "enablessl":
			enabled, err := strconv.ParseBool(value)
			if err != nil {
				return fmt.Errorf("invalid ssl option: %w", err)
			}
			config.ssl = enabled
		case "hostverification", "verifyhostname", "sslhostnameverification", "hostnameverification":
			enabled, err := strconv.ParseBool(value)

View on GitHub (pinned to c0390bff16)

Solutions

1. Set numconns to an integer between 1 and 32.
2. Remove the parameter to use the driver's default connection-per-host count.
3. If you need more concurrency than the cap allows, scale via hosts or a separate session instead of raising numconns.
4. Quote/escape the value if it comes from a URL query built programmatically (e.g. stray '2.5' from a float).

Example fix

// before
cassandra://host:9042?numconns=64
// after
cassandra://host:9042?numconns=8

n, err := strconv.Atoi(numConns)
if err != nil || n < 1 || n > 32 {
	return fmt.Errorf("numconns must be an integer 1-32, got %q", numConns)
}

cfg, err := parseCassandraConfig(dsn)
if err != nil {
	if strings.Contains(err.Error(), "numconns must be between 1 and 32") {
		return fmt.Errorf("clamp numconns to 1-32: %w", err)
	}
	return err
}

When it happens

Trigger: numconns=0, numconns=50, connectionsperhost=abc, or numconns=2.5 in a cassandra:// URL.

Common situations: Tuning connection pools aggressively for high-throughput workloads and exceeding the cap, setting 0 expecting 'auto', or non-integer values from templated config.

Related errors

• protocolversion must be between 3 and 5
• serialconsistency must be SERIAL or LOCAL_SERIAL
• 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/dc28a27ab428826a. Report an issue: GitHub.