apache/cassandra · error · InvalidConstraintDefinitionException

Constraint '%s' can be used only for columns of type %s but

Error message

Constraint '%s' can be used only for columns of type %s but it was %s

What it means

This InvalidConstraintDefinitionException is thrown by ColumnConstraint.validateTypes when a constraint is attached to a column whose type is not in the constraint's list of supported types. Cassandra validates constraint/type compatibility at schema definition time (CREATE/ALTER TABLE) so invalid constraints never reach the write path. The message reports the allowed types and the actual column type class.

Source

Thrown at src/java/org/apache/cassandra/cql3/constraints/ColumnConstraint.java:164

     */
    public abstract ConstraintType getConstraintType();


    /**
     * Tells what types of columns are supported by this constraint.
     * Returning empty list or null means that all types are supported.
     *
     * @return supported types for given constraint
     */
    public abstract List<AbstractType<?>> getSupportedTypes();

    protected void validateTypes(ColumnMetadata columnMetadata)
    {
        if (getSupportedTypes() == null || getSupportedTypes().isEmpty())
            return;

        if (!getSupportedTypes().contains(columnMetadata.type.unwrap()))
            throw new InvalidConstraintDefinitionException(format("Constraint '%s' can be used only for columns of type %s but it was %s",
                                                                  name(),
                                                                  getSupportedTypes(),
                                                                  columnMetadata.type.getClass()));
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Change the constrained column to one of the supported types listed in the message (or change the column type via ALTER).
2. Remove the constraint from the incompatible column.
3. Extend the constraint's getSupportedTypes() to include the column type if you control the constraint implementation.
4. Wrap the column in the required type (e.g. make it a text column) if the constraint semantics allow it.

Example fix

// before
CREATE TABLE ks.t (id uuid PRIMARY KEY, flags int CONSTRAINT CHECK LENGTH(3..10));
// after
CREATE TABLE ks.t (id uuid PRIMARY KEY, name text CONSTRAINT CHECK LENGTH(3..10));

Set<AbstractType<?>> supported = constraint.getSupportedTypes();
if (supported != null && !supported.contains(column.type.unwrap()))
    throw new IllegalArgumentException("Constraint " + constraint.name() + " not applicable to column type " + column.type.asCQL3Type());

static boolean constraintSupports(ColumnConstraint<?> c, ColumnMetadata col) {
    var s = c.getSupportedTypes();
    return s == null || s.isEmpty() || s.contains(col.type.unwrap());
}

When it happens

Trigger: Declaring a column constraint (e.g. LENGTH, JSON) on a column whose AbstractType is not contained in the constraint's getSupportedTypes() — e.g. applying a LENGTH constraint to a boolean or uuid column in CREATE TABLE or ALTER TABLE.

Common situations: Copying constraint DDL from an int/text column example to an incompatible column type; changing a column's type with ALTER TABLE so an existing constraint's supported type no longer matches; tools generating schema DDL that apply constraints indiscriminately.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Constraint cannot be defined on the column <name> of type <t
• There are duplicate constraint definitions on column '%s': %
• Constraint %s was not specified on a column it operates on:
• Constraint %s does not accept any arguments.
• %s constraint can not be specified on a %s key column '%s'

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