apache/cassandra · error · InvalidRequestException

Cannot create ENTRIES index on frozen map clustering column

Error message

Cannot create ENTRIES index on frozen map clustering column '%s'. Map entry predicates (column[key] = value) are not supported on clustering columns. Use FULL, KEYS, or VALUES index instead.

What it means

An ENTRIES (KEYS_AND_VALUES) index on a frozen map stored in a clustering column would be unqueryable, because the map[key] = value entry predicate cannot be evaluated on clustering columns. Cassandra rejects it at creation time rather than allowing an index that no query can use.

Source

Thrown at src/java/org/apache/cassandra/cql3/statements/schema/CreateIndexStatement.java:312

        if (!baseType.isCollection() && target.type != Type.SIMPLE)
            throw ire(NON_COLLECTION_SIMPLE_INDEX, target.type, column);

        // Frozen collections are only supported with SAI indexes.
        if (isNonSAIIndex && baseType.isCollection() && !column.type.isMultiCell())
        {
            if (target.type == Type.VALUES || target.type == Type.KEYS || target.type == Type.KEYS_AND_VALUES)
            {
                throw ire(CREATE_ON_FROZEN_COLUMN, target.type.toString(), column.name, column.name);
            }
        }

        if (!(baseType instanceof MapType) && (target.type == Type.KEYS || target.type == Type.KEYS_AND_VALUES ))
            throw ire(CREATE_WITH_NON_MAP_TYPE, target.type, column);

        // Can't query map[key]=value on clustering key columns, so ENTRIES index would be not queryable.
        if (column.isClusteringColumn() && baseType instanceof MapType && !column.type.isMultiCell()
            && target.type == Type.KEYS_AND_VALUES)
            throw ire(ENTRIES_INDEX_ON_FROZEN_MAP_CLUSTERING_KEY_NOT_SUPPORTED, column.name);

        if (column.type.isUDT() && column.type.isMultiCell())
            throw ire(CREATE_ON_NON_FROZEN_UDT, column);
    }

    /**
     * Checks if the given index attributes represent a Storage Attached Index.
     */
    private boolean isSAIIndex(IndexAttributes attrs)
    {
        return attrs.isCustom && IndexMetadata.isSAIIndex(attrs.customClass);
    }

    private String generateIndexName(KeyspaceMetadata keyspace, List<IndexTarget> targets)
    {
        String baseName = targets.size() == 1
                        ? IndexMetadata.generateDefaultIndexName(tableName, targets.get(0).column)
                        : IndexMetadata.generateDefaultIndexName(tableName);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Use a FULL, KEYS, or VALUES index on the frozen map clustering column instead of ENTRIES.
Move the map out of the clustering key into a regular column if entry predicates (col[key]=value) are required.
Remodel the data so queried keys become their own columns or partition/clustering key components.

Example fix

// before
CREATE INDEX ON t (entries(attrs)); -- attrs is frozen<map<text,text>> clustering column
// after
CREATE INDEX ON t (full(attrs)); -- or KEYS/VALUES as appropriate

Defensive patterns

Strategy: validation

Validate before calling

if (column.isClusteringColumn() && baseType instanceof MapType && !column.type.isMultiCell() && target.type === 'KEYS_AND_VALUES') throw new Error('ENTRIES index on frozen map clustering column is not queryable');

Type guard

const entriesTargetUsable = (col, baseType) => !(col.isClusteringColumn() && baseType instanceof MapType && !col.type.isMultiCell());

Try / catch

try { session.execute(ddl); } catch (e) { if (/Cannot create ENTRIES index on frozen map clustering column/.test(e.message)) { /* use FULL/KEYS/VALUES or move column out of clustering key */ } else throw e; }

Prevention

Avoid entry predicates against clustering-key maps by design
Put queryable maps in regular columns, not clustering keys

When it happens

Trigger: `CREATE INDEX ON t (entries(map_col))` where map_col is a frozen<map<...>> declared as a clustering key column, with a non-multi-cell map and target type KEYS_AND_VALUES.

Common situations: Modeling per-row attribute maps as clustering columns for ordering, then trying entry predicates; porting index DDL from a regular-column layout to a clustering-column layout.

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/0e0d81dcdf738922. Report an issue: GitHub.