apache/cassandra · error · java.lang.IllegalArgumentException

Counter modification statements are not supported

Error message

Counter modification statements are not supported

What it means

CQLSSTableWriter writes directly into SSTables without the coordinator-side counter machinery (counter shards, leader distribution), so counter modifications cannot be represented. The Builder rejects any prepared modification statement for which isCounter() is true with an IllegalArgumentException.

Solutions

Do not bulk-load counter tables with CQLSSTableWriter; use normal CQL increment/decrement statements via a driver
Restructure the schema to store the value as a regular column in a non-counter table if bulk loading is essential
Split the workload: load non-counter data offline, apply counter deltas online

Example fix

// before
String cql = "UPDATE ks.counters SET hits = hits + ? WHERE k = ?"; // rejected
// after
// use a session/driver statement instead of CQLSSTableWriter for counter tables
session.execute("UPDATE ks.counters SET hits = hits + ? WHERE k = ?", delta, key);

Defensive patterns

Strategy: validation

Validate before calling

if (schema is a counter table or statement targets counter columns)
    throw new IllegalArgumentException("Use regular CQL for counter tables, not CQLSSTableWriter");

Try / catch

try { builder.build(); }
catch (IllegalArgumentException e) {
    if (e.getMessage().equals("Counter modification statements are not supported"))
        // route through driver/LWT path instead
}

Prevention

Check table metadata (counter columns) before choosing the bulk-load path
Exclude counter tables from offline loading tooling
Document counter tables as unsupported for SSTable writers

When it happens

Trigger: Passing a counter statement such as 'UPDATE ks.t SET counter_col = counter_col + ? WHERE k = ?' (or a counter-table INSERT) to CQLSSTableWriter and calling build().

Common situations: Bulk-loading scripts pointed at counter tables; developers assuming bulk-load API parity with all table types.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/io/sstable/CQLSSTableWriter.java:919

            return builder.build();
        }

        /**
         * Prepares modification statement for writing data to SSTable
         *
         * @return prepared modification statement and it's bound names
         */
        private ModificationStatement prepareModificationStatement()
        {
            ClientState state = ClientState.forInternalCalls();
            ModificationStatement preparedModificationStatement = modificationStatement.prepare(state);
            preparedModificationStatement.validate(state);

            if (preparedModificationStatement.hasConditions())
                throw new IllegalArgumentException("Conditional statements are not supported");
            if (preparedModificationStatement.isCounter())
                throw new IllegalArgumentException("Counter modification statements are not supported");
            if (preparedModificationStatement.getBindVariables().isEmpty())
                throw new IllegalArgumentException("Provided preparedModificationStatement statement has no bind variables");

            return preparedModificationStatement;
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)