apache/cassandra · error · InvalidRequestException

Map-entry predicates on frozen map column

Error message

Map-entry predicates on frozen map column %s are not supported

What it means

Map-entry predicates (map[col] = value style restrictions) are only supported on non-frozen maps. When a CONTAINS/CONTAINS KEY restriction is merged with a map-element expression on a frozen collection column, MergedRestriction.validate throws this error because frozen collections are stored as a single blob and cannot be indexed per-entry.

Solutions

1. Drop the map-entry/CONTAINS restriction on the frozen column and query on the full frozen value with EQ instead
2. Redefine the column as a non-frozen map if per-entry predicates are required (requires table migration)
3. Create a separate lookup/denormalized table keyed by the map key

Example fix

// before
CREATE TABLE t (id int PRIMARY KEY, tags frozen<map<text,text>>);
SELECT * FROM t WHERE tags['env'] = 'prod';
// after
CREATE TABLE t (id int PRIMARY KEY, tags map<text,text>);
SELECT * FROM t WHERE tags['env'] = 'prod';

// guard before issuing a map-entry predicate
ColumnMetadata col = schema.getColumn("tags");
if (col.type.isFrozenCollection())
    throw new IllegalArgumentException("map-entry predicates unsupported on frozen column " + col.name);

boolean supportsMapEntryPredicate(ColumnMetadata col) { return col.type instanceof MapType && !col.type.isFrozenCollection(); }

When it happens

Trigger: A query like frozen_map_col CONTAINS KEY 'k' or merging a CONTAINS restriction with a map-entry equality (frozen_map_col['k'] = v) on a column declared FROZEN<map<...>>; validate() in MergedRestriction detects isMapElementExpression() on a frozenCollection type.

Common situations: Schema was altered to frozen (or created as frozen) while queries assume thawed per-entry lookup semantics; migrating from thawed to frozen collections for compaction reasons breaks existing queries.

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

• Map-entry predicates on frozen map column
• Invalid non-frozen collection type
• Invalid operation ( ) for frozen collection column
• A TTL must be greater or equal to 0, but was
• A user type cannot contain counters

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/restrictions/MergedRestriction.java:137

    public boolean isMultiColumn()
    {
        return isMultiColumn;
    }

    private static void validate(SimpleRestriction restriction, SimpleRestriction other)
    {
        checkOperator(restriction);
        checkOperator(other);

        if (restriction.isContains() != other.isContains())
        {
            SimpleRestriction mapEntryRestriction = restriction.isContains() ? restriction : other;
            if (mapEntryRestriction.isMapElementExpression())
            {
                ColumnMetadata column = mapEntryRestriction.firstColumn();
                if (column.type.isFrozenCollection())
                {
                    throw invalidRequest(Relation.FROZEN_MAP_ENTRY_PREDICATES_NOT_SUPPORTED, column.name);
                }
            }

            throw invalidRequest("Collection column %s can only be restricted by CONTAINS, CONTAINS KEY, NOT_CONTAINS, NOT_CONTAINS_KEY" +
                                 " or map-entry equality if it already restricted by one of those",
                                 restriction.firstColumn().name);
        }

        if (restriction.isSlice() && other.isSlice())
        {
            ColumnMetadata firstColumn = restriction.firstColumn();
            ColumnMetadata otherFirstColumn = other.firstColumn();
            if (!firstColumn.equals(otherFirstColumn))
            {
                ColumnMetadata column = firstColumn.position() > otherFirstColumn.position() ? firstColumn
                                                                                             : otherFirstColumn;

                throw invalidRequest("Column \"%s\" cannot be restricted by two inequalities not starting with the same column",

View on GitHub (pinned to 88fd0f6a0e)