apache/cassandra · error · InvalidRequestException

You must use conditional updates for serializable writes

Error message

You must use conditional updates for serializable writes

What it means

SERIAL (and related) consistency levels apply only to the serial phase of lightweight-transaction (LWT) operations; they cannot be used for plain writes. validateForWrite rejects any serial-family level for a non-conditional write. A serializable write on Cassandra requires a conditional update (INSERT ... IF NOT EXISTS / UPDATE ... IF).

Source

Thrown at src/java/org/apache/cassandra/db/ConsistencyLevel.java:237

    public void validateForRead() throws InvalidRequestException
    {
        switch (this)
        {
            case ANY:
                throw new InvalidRequestException("ANY ConsistencyLevel is only supported for writes");
        }
    }

    public void validateForWrite() throws InvalidRequestException
    {
        switch (this)
        {
            case SERIAL:
            case UNSAFE_DELAY_SERIAL:
            case LOCAL_SERIAL:
            case UNSAFE_DELAY_LOCAL_SERIAL:
                throw new InvalidRequestException("You must use conditional updates for serializable writes");
        }
    }

    // This is the same than validateForWrite really, but we include a slightly different error message for SERIAL/LOCAL_SERIAL
    public void validateForCasCommit(AbstractReplicationStrategy replicationStrategy) throws InvalidRequestException
    {
        switch (this)
        {
            case EACH_QUORUM:
                requireNetworkTopologyStrategy(replicationStrategy);
                break;
            case SERIAL:
            case UNSAFE_DELAY_SERIAL:
            case LOCAL_SERIAL:
            case UNSAFE_DELAY_LOCAL_SERIAL:
                throw new InvalidRequestException(this + " is not supported as conditional update commit consistency. Use ANY if you mean \"make sure it is accepted but I don't care how many replicas commit it for non-SERIAL reads\"");
        }
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Use a conditional statement (INSERT ... IF NOT EXISTS or UPDATE ... IF <condition>) when serial consistency is required.
For plain writes, switch consistency to QUORUM/LOCAL_QUORUM/EACH_QUORUM as appropriate.
Set the serial consistency separately via the driver's serial consistency API (setSerialConsistencyLevel) rather than the write consistency.
In cqlsh, run `CONSISTENCY QUORUM;` before non-conditional writes.

Example fix

// before
session.execute(SimpleStatement.builder("INSERT INTO t(k,v) VALUES (1,2)")
    .setConsistencyLevel(ConsistencyLevel.SERIAL).build());
// after
session.execute(SimpleStatement.builder("INSERT INTO t(k,v) VALUES (1,2) IF NOT EXISTS")
    .setConsistencyLevel(ConsistencyLevel.QUORUM)
    .setSerialConsistencyLevel(ConsistencyLevel.SERIAL).build());

Defensive patterns

Strategy: validation

Validate before calling

// Client-side guard for plain writes
if (cl == ConsistencyLevel.SERIAL || cl == ConsistencyLevel.LOCAL_SERIAL)
    throw new IllegalArgumentException("serial CL requires conditional update");

Try / catch

catch (InvalidRequestException e) {
    if (e.getMessage().contains("conditional updates")) {
        // either make the statement conditional or drop to QUORUM
        statement.setConsistencyLevel(ConsistencyLevel.QUORUM);
    } else throw e;
}

Prevention

Set serial consistency only via setSerialConsistencyLevel on LWT statements.
Keep cqlsh CONSISTENCY at QUORUM for general work; use SERIAL CONSISTENCY for LWT sessions.
Document the two-level (serial vs commit) consistency model for the team.
Test LWT statements in a staging keyspace before deploying.

When it happens

Trigger: Executing an unconditional INSERT/UPDATE/BATCH write with consistency SERIAL, LOCAL_SERIAL (or the UNSAFE_DELAY variants), e.g. `CONSISTENCY SERIAL;` then a plain INSERT in cqlsh.

Common situations: Confusion between the serial and commit consistency of LWTs; porting code from systems where serializable implies all writes; leftover CONSISTENCY SERIAL in cqlsh sessions.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/1eb5c2ee7d2ad6d0. Report an issue: GitHub.