What causes "Counters are not allowed inside collections: " in apache/cassandra?

Move the counter to a top-level column: `counter_val counter` keyed by the item id in the primary key instead of a map of counters

apache/cassandra · error · InvalidRequestException

Counters are not allowed inside collections:

Error message

Counters are not allowed inside collections:

What it means

Cassandra rejects counter columns used as elements or values of any collection type (list, set, map value) unless the parse is internal (supercolumn schema compatibility). Counters cannot be embedded in collections because counter updates are deltas merged per-cell, which the collection conflict resolution cannot support.

Source

Thrown at src/java/org/apache/cassandra/cql3/CQL3Type.java:865

                return prepare(keyspace, udts, false);
            }

            public CQL3Type prepareInternal(String keyspace, Types udts)
            {
                return prepare(keyspace, udts, true);
            }

            public CQL3Type prepare(String keyspace, Types udts, boolean isInternal) throws InvalidRequestException
            {
                assert values != null : "Got null values type for a collection";

                if (!frozen && values.supportsFreezing() && !values.frozen)
                    throwNestedNonFrozenError(values);

                // we represent supercolumns as maps, internally, and we do allow counters in supercolumns. Thus,
                // for internal type parsing (think schema) we have to make an exception and allow counters as (map) values
                if (values.isCounter() && !isInternal)
                    throw new InvalidRequestException("Counters are not allowed inside collections: " + this);

                if (values.isDuration() && kind == Kind.SET)
                    throw new InvalidRequestException("Durations are not allowed inside sets: " + this);

                if (keys != null)
                {
                    if (keys.isCounter())
                        throw new InvalidRequestException("Counters are not allowed inside collections: " + this);
                    if (keys.isDuration())
                        throw new InvalidRequestException("Durations are not allowed as map keys: " + this);
                    if (!frozen && keys.supportsFreezing() && !keys.frozen)
                        throwNestedNonFrozenError(keys);
                }

                AbstractType<?> valueType = values.prepare(keyspace, udts).getType();
                switch (kind)
                {
                    case LIST:

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Move the counter to a top-level column: `counter_val counter` keyed by the item id in the primary key instead of a map of counters
Use a frozen<...> wrapper only if the whole collection is truly static and updated wholesale — but note frozen collections still cannot contain counters; prefer per-row counters
Model counters in a separate table with one counter column per entity
If this is internal schema parsing of legacy supercolumn data, it is not a user error — do not attempt to fix in user CQL

Example fix

// before
CREATE TABLE stats (id uuid PRIMARY KEY, per_item map<text, counter>);
// after
CREATE TABLE stats (id uuid, item text, hits counter, PRIMARY KEY (id, item));

Defensive patterns

Strategy: validation

Validate before calling

boolean usesCounterInCollection(String cqlTypeDecl) {
    String lower = cqlTypeDecl.toLowerCase();
    return lower.matches("(list|set|map)\\s*<.*counter.*");
}
// call before issuing CREATE TABLE/ALTER TABLE

Try / catch

try { session.execute(schemaDdl); } catch (com.datastax.driver.core.exceptions.InvalidQueryException e) { if (e.getMessage().contains("Counters are not allowed inside collections")) { /* redesign schema: counters as top-level columns */ } else throw e; }

Prevention

Never declare counter inside list/set/map/tuple — counters must be top-level columns
Model per-entity counters with a separate table and clustering key
Validate schema DDL in a test keyspace before applying to production

When it happens

Trigger: Declaring a column like `set<counter>`, `list<counter>`, or `map<text, counter>` in CREATE TABLE / ALTER TABLE, or using counter inside a nested collection type definition.

Common situations: Developers trying to keep per-item counters in a set or map instead of using one counter column per row; schema migrations porting from other databases.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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