t8y2/dbx · error

serial consistency must be SERIAL or LOCAL_SERIAL

Error message

serial consistency must be SERIAL or LOCAL_SERIAL

What it means

The serial-consistency value parsed as a valid gocql consistency but is not one of the two legal serial consistencies (SERIAL or LOCAL_SERIAL). Ordinary consistencies like QUORUM are rejected for serial operations because C* only permits SERIAL/LOCAL_SERIAL there.

Source

Thrown at agents/drivers/cassandra-go/config_file.go:71

		config.requestTimeout = value
	}
	if value, ok, err := hoconString(parsed, javaDriverConfigPrefix+"basic.request.consistency"); err != nil {
		return err
	} else if ok {
		if _, err := gocql.ParseConsistencyWrapper(value); err != nil {
			return err
		}
		config.consistency = value
	}
	if value, ok, err := hoconString(parsed, javaDriverConfigPrefix+"basic.request.serial-consistency"); err != nil {
		return err
	} else if ok {
		consistency, err := gocql.ParseConsistencyWrapper(value)
		if err != nil {
			return err
		}
		if consistency != gocql.Serial && consistency != gocql.LocalSerial {
			return fmt.Errorf("serial consistency must be SERIAL or LOCAL_SERIAL")
		}
		config.serialConsistency = value
	}
	if value, ok, err := hoconInt(parsed, javaDriverConfigPrefix+"basic.request.page-size"); err != nil {
		return err
	} else if ok {
		if value < 1 {
			return fmt.Errorf("page size must be positive")
		}
		config.pageSize = value
	}
	if value, ok, err := hoconString(parsed, javaDriverConfigPrefix+"basic.load-balancing-policy.local-datacenter"); err != nil {
		return err
	} else if ok {
		config.localDatacenter = value
	}
	if value, ok, err := hoconString(parsed, javaDriverConfigPrefix+"basic.load-balancing-policy.class"); err != nil {
		return err

View on GitHub (pinned to c0390bff16)

Solutions

1. Set serial-consistency to exactly 'SERIAL' or 'LOCAL_SERIAL'
2. If you intended regular request consistency, set basic.request.consistency instead
3. Remove the key to use the driver default (SERIAL)

Example fix

// before
datastax-java-driver { basic { request.serial-consistency = "QUORUM" } }
// after
datastax-java-driver { basic { request.serial-consistency = "LOCAL_SERIAL" } }

sc := strings.ToUpper(cfg.SerialConsistency)
if sc != "" && sc != "SERIAL" && sc != "LOCAL_SERIAL" {
    return fmt.Errorf("serial-consistency must be SERIAL or LOCAL_SERIAL, got %q", cfg.SerialConsistency)
}

func isSerialConsistency(v string) bool {
    switch strings.ToUpper(v) { case "SERIAL", "LOCAL_SERIAL": return true }
    return false
}

if err := parseCassandraConfig(raw); err != nil {
    if strings.Contains(err.Error(), "serial consistency must be SERIAL or LOCAL_SERIAL") {
        return fmt.Errorf("set basic.request.serial-consistency to SERIAL or LOCAL_SERIAL: %w", err)
    }
    return err
}

When it happens

Trigger: Setting datastax-java-driver.basic.request.serial-consistency (via applyJavaDriverHOCON) to a value that ParseConsistencyWrapper accepts but is not Serial/LocalSerial, e.g. 'QUORUM' or 'ONE'.

Common situations: Confusing regular consistency with serial consistency in config; copying consistency settings from another driver section; defaults inherited from a template using QUORUM.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• serialconsistency 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/2f0c9f338682d031. Report an issue: GitHub.