apache/cassandra · error · InvalidConstraintDefinitionException

%s constraint can not be specified on a %s key column '%s'

Error message

%s constraint can not be specified on a %s key column '%s'

What it means

NotNullConstraint.validate rejects applying a NOT NULL constraint to any primary key column (partition key or clustering column). Primary key columns are already implicitly required by Cassandra's data model, so the explicit constraint is redundant and disallowed, thrown as InvalidConstraintDefinitionException at schema definition time. The message names partition vs clustering and the column.

Source

Thrown at src/java/org/apache/cassandra/cql3/constraints/NotNullConstraint.java:59

    }

    public NotNullConstraint(List<String> args)
    {
        super(FUNCTION_NAME, args);
    }

    @Override
    public void internalEvaluate(AbstractType<?> valueType, Operator relationType, String term, ByteBuffer columnValue)
    {
        // on purpose empty as evaluate method already covered nullity
    }

    @Override
    public void validate(ColumnMetadata columnMetadata, String term) throws InvalidConstraintDefinitionException
    {
        super.validate(columnMetadata, term);
        if (columnMetadata.isPrimaryKeyColumn())
            throw new InvalidConstraintDefinitionException(format("%s constraint can not be specified on a %s key column '%s'",
                                                                  name,
                                                                  columnMetadata.isPartitionKey() ? "partition" : "clustering",
                                                                  columnMetadata.name));
    }

    @Override
    public List<AbstractType<?>> getSupportedTypes()
    {
        return null;
    }

    @Override
    public String toString()
    {
        return CQL_FUNCTION_NAME;
    }

    @Override

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove the NOT NULL constraint from the primary key column — key columns are inherently non-null.
2. If the intent was to enforce presence on a data column, apply the constraint to that column instead.
3. Fix schema-generation code to skip primary key columns when emitting NOT NULL constraints.

Example fix

// before
CREATE TABLE ks.t (id uuid NOT NULL PRIMARY KEY, name text);
// after
CREATE TABLE ks.t (id uuid PRIMARY KEY, name text NOT NULL);

if (columnMetadata.isPrimaryKeyColumn() && constraints.stream().anyMatch(c -> c instanceof NotNullConstraint))
    throw new IllegalArgumentException("NOT NULL is redundant on primary key column " + columnMetadata.name);

static boolean notNullAllowed(ColumnMetadata col) { return !col.isPrimaryKeyColumn(); }

When it happens

Trigger: CREATE TABLE / ALTER TABLE declaring `NOT NULL` on a column that isPrimaryKeyColumn() — e.g. `PRIMARY KEY (id)` plus `id uuid NOT NULL`, or a clustering column with NOT NULL.

Common situations: Porting schemas from relational databases where NOT NULL on keys is customary; schema-generator tools that annotate every non-nullable entity field; misunderstanding that keys already cannot be null.

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

• Constraint '%s' can be used only for columns of type %s but
• 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.

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