{"record":{"id":"760a856c4bcb6919","repo":"apache/cassandra","slug":"constraint-cannot-be-defined-on-the-column-name","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"validation","errorClass":"InvalidConstraintDefinitionException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/cql3/constraints/ColumnConstraints.java","lineNumber":145,"sourceCode":"    }\n\n    public boolean containsNotNullConstraint()\n    {\n        for (ColumnConstraint<?> c : constraints)\n        {\n            if (c.toString().equals(NotNullConstraint.CQL_FUNCTION_NAME))\n                return true;\n        }\n\n        return false;\n    }\n\n    @Override\n    public void validate(ColumnMetadata columnMetadata) throws InvalidConstraintDefinitionException\n    {\n        if (!columnMetadata.type.isConstrainable())\n        {\n            throw new InvalidConstraintDefinitionException(\"Constraint cannot be defined on the column \"\n                                                           + columnMetadata.name + \" of type \" + columnMetadata.type.asCQL3Type()\n                                                           + \" for the table \" + columnMetadata.ksName + '.' + columnMetadata.cfName + '.' +\n                                                           (columnMetadata.type.isCollection() ? \" When using collections, constraints can be used only of frozen collections.\" : \"\"));\n        }\n\n        // this will look at constraints as a whole,\n        // checking if combinations of a particular constraint make sense (duplicities, satisfiability etc.).\n        for (SatisfiabilityChecker satisfiabilityChecker : ConstraintType.getSatisfiabilityCheckers())\n            satisfiabilityChecker.checkSatisfiability(constraints, columnMetadata);\n\n        // this validation will check whether it makes sense to execute such constraint on a given column\n        for (ColumnConstraint<?> constraint : constraints)\n            constraint.validate(columnMetadata);\n    }\n\n    @Override\n    public ConstraintType getConstraintType()\n    {","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/constraints/ColumnConstraints.java#L127-L163","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Declare the collection as FROZEN (e.g. `frozen<map<text, int>>`) so it becomes constrainable.","Remove the constraint from the non-frozen collection column.","Move the constrained data into a separate scalar or frozen column."],"exampleFix":"// before\nCREATE TABLE ks.t (id uuid PRIMARY KEY, tags list<text> CONSTRAINT CHECK LENGTH(1..5));\n// after\nCREATE TABLE ks.t (id uuid PRIMARY KEY, tags frozen<list<text>> CONSTRAINT CHECK LENGTH(1..5));","handlingStrategy":"validation","validationCode":"if (!columnMetadata.type.isConstrainable())\n    throw new IllegalArgumentException(\"Column \" + columnMetadata.name + \" is not constrainable; freeze collections to constrain them\");","typeGuard":"static boolean isConstrainableColumn(ColumnMetadata col) { return col.type.isConstrainable(); }","tryCatchPattern":null,"preventionTips":["Use FROZEN keyword on collections that need constraints","Validate collection column definitions in schema builders before generating DDL","Document in your data model which columns may carry constraints"],"tags":["cql","schema","constraints","collections","frozen"],"backgroundTag":"schema-validation-failed","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}