t8y2/dbx · error

serialconsistency must be SERIAL or LOCAL_SERIAL

Error message

serialconsistency must be SERIAL or LOCAL_SERIAL

What it means

The 'serialconsistency' URL parameter is parsed with gocql.ParseConsistencyWrapper and must resolve to gocql.Serial or gocql.LocalSerial. Any other consistency level (e.g. QUORUM) or unparseable name yields this error, because serial consistency only accepts those two levels.

Source

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

			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)
			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)

View on GitHub (pinned to c0390bff16)

Solutions

1. Set serialconsistency=SERIAL or serialconsistency=LOCAL_SERIAL exactly.
2. If you meant ordinary query consistency, use the consistency parameter instead.
3. Trim whitespace and fix casing in the URL query value.

Example fix

// before
cassandra://host:9042?serialconsistency=QUORUM
// after
cassandra://host:9042?serialconsistency=LOCAL_SERIAL

switch strings.ToUpper(serialCons) {
case "SERIAL", "LOCAL_SERIAL":
default:
	return fmt.Errorf("serialconsistency must be SERIAL or LOCAL_SERIAL, got %q", serialCons)
}

cfg, err := parseCassandraConfig(dsn)
if err != nil {
	if strings.Contains(err.Error(), "serialconsistency must be SERIAL or LOCAL_SERIAL") {
		return fmt.Errorf("serialconsistency only accepts SERIAL/LOCAL_SERIAL; use 'consistency' for regular levels: %w", err)
	}
	return err
}

When it happens

Trigger: serialconsistency=QUORUM, serialconsistency=serial (lowercase if the parser is case-sensitive), serialconsistency=ONE, or any invalid token in a cassandra:// URL.

Common situations: Confusing regular consistency with serial consistency (LWT/lightweight transactions), copying a normal consistency setting into the serialconsistency key, or case/whitespace mistakes like ' local_serial'.

Related errors

• serial consistency must be SERIAL or LOCAL_SERIAL
• protocolversion must be between 3 and 5
• numconns must be between 1 and 32
• pagesize must be positive
• retries must be between 0 and 1000

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