apache/cassandra · error · InvalidConstraintDefinitionException

Constraint cannot be defined on the column <name> of type <t

Error message

Constraint cannot be defined on the column <name> of type <type> for the table <ks>.<cf>. When using collections, constraints can be used only of frozen collections.

What it means

ColumnConstraints.validate rejects defining any constraint on a column whose type is not 'constrainable'. Only frozen collections and scalar types are constrainable — non-frozen (mutable) collections cannot be constrained because their contents change without a full-value write, making constraint evaluation unreliable. The message indicates the table/column and, for collections, hints that only frozen collections may be constrained.

Source

Thrown at src/java/org/apache/cassandra/cql3/constraints/ColumnConstraints.java:145

    }

    public boolean containsNotNullConstraint()
    {
        for (ColumnConstraint<?> c : constraints)
        {
            if (c.toString().equals(NotNullConstraint.CQL_FUNCTION_NAME))
                return true;
        }

        return false;
    }

    @Override
    public void validate(ColumnMetadata columnMetadata) throws InvalidConstraintDefinitionException
    {
        if (!columnMetadata.type.isConstrainable())
        {
            throw new InvalidConstraintDefinitionException("Constraint cannot be defined on the column "
                                                           + columnMetadata.name + " of type " + columnMetadata.type.asCQL3Type()
                                                           + " for the table " + columnMetadata.ksName + '.' + columnMetadata.cfName + '.' +
                                                           (columnMetadata.type.isCollection() ? " When using collections, constraints can be used only of frozen collections." : ""));
        }

        // this will look at constraints as a whole,
        // checking if combinations of a particular constraint make sense (duplicities, satisfiability etc.).
        for (SatisfiabilityChecker satisfiabilityChecker : ConstraintType.getSatisfiabilityCheckers())
            satisfiabilityChecker.checkSatisfiability(constraints, columnMetadata);

        // this validation will check whether it makes sense to execute such constraint on a given column
        for (ColumnConstraint<?> constraint : constraints)
            constraint.validate(columnMetadata);
    }

    @Override
    public ConstraintType getConstraintType()
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Declare the collection as FROZEN (e.g. `frozen<map<text, int>>`) so it becomes constrainable.
2. Remove the constraint from the non-frozen collection column.
3. Move the constrained data into a separate scalar or frozen column.

Example fix

// before
CREATE TABLE ks.t (id uuid PRIMARY KEY, tags list<text> CONSTRAINT CHECK LENGTH(1..5));
// after
CREATE TABLE ks.t (id uuid PRIMARY KEY, tags frozen<list<text>> CONSTRAINT CHECK LENGTH(1..5));

if (!columnMetadata.type.isConstrainable())
    throw new IllegalArgumentException("Column " + columnMetadata.name + " is not constrainable; freeze collections to constrain them");

static boolean isConstrainableColumn(ColumnMetadata col) { return col.type.isConstrainable(); }

When it happens

Trigger: CREATE TABLE / ALTER TABLE adding a constraint to a column whose type is not constrainable, e.g. a non-frozen collection like 'map<text, int>' or a counter/complex type. Reached via ColumnConstraints.validate from schema validation.

Common situations: Applying a LENGTH or JSON constraint to a list/set/map column that was declared without the FROZEN keyword; schema generated by ORMs that add constraints to collection columns.

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

• Non-frozen UDTs with nested non-frozen collections are not s
• frozen<> is only allowed on collections, tuples, and user-de
• Non-frozen collections are not allowed inside collections:
• Non-frozen UDTs are not allowed inside collections:
• Invalid operation (%s) for frozen list column %s

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