apache/cassandra · error · InvalidConstraintDefinitionException

There are duplicate constraint definitions on column '%s': %

Error message

There are duplicate constraint definitions on column '%s': %s

What it means

When multiple NEQ (non-equal) constraints exist on one column, the checker collects their terms into a TreeSet; if the same term appears twice, the constraint definitions are redundant, and InvalidConstraintDefinitionException is thrown naming the column and the duplicate constraint. Detected at schema-definition time in checkNumberOfConstraints.

Source

Thrown at src/java/org/apache/cassandra/cql3/constraints/AbstractFunctionSatisfiabilityChecker.java:113

    private void checkNumberOfConstraints(ColumnMetadata columnMetadata, Pair<List<CONSTRAINT_TYPE>, List<CONSTRAINT_TYPE>> filteredConstraints)
    {
        List<? extends AbstractFunctionConstraint<CONSTRAINT_TYPE>> allConstraints = filteredConstraints.left;
        List<? extends AbstractFunctionConstraint<CONSTRAINT_TYPE>> notEqualConstraints = filteredConstraints.right;

        if ((allConstraints.size() - notEqualConstraints.size() > 2))
        {
            throw new InvalidConstraintDefinitionException(format("There can not be more than 2 constraints (not including non-equal relations) on a column '%s' but you have specified %s",
                                                                  columnMetadata.name,
                                                                  allConstraints.size()));
        }

        if (notEqualConstraints.size() > 1)
        {
            Set<String> uniqueTerms = new TreeSet<>();
            for (AbstractFunctionConstraint<CONSTRAINT_TYPE> notEqual : notEqualConstraints)
            {
                if (!uniqueTerms.add(notEqual.term()))
                    throw new InvalidConstraintDefinitionException(format("There are duplicate constraint definitions on column '%s': %s",
                                                                          columnMetadata.name,
                                                                          notEqual));
            }
        }
    }

    private void ensureSatisfiability(ColumnMetadata columnMetadata,
                                      String constraintName,
                                      List<CONSTRAINT_TYPE> allConstraints)
    {
        if (allConstraints.size() != 2)
            return;

        Operator firstRelation = allConstraints.get(0).relationType();
        String firstTerm = allConstraints.get(0).term();
        Operator secondRelation = allConstraints.get(1).relationType();
        String secondTerm = allConstraints.get(1).term();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Remove the duplicate NEQ constraint, keeping a single occurrence of each distinct term.
  2. Diff the CREATE/ALTER TABLE DDL against the existing schema to spot already-present constraints.
  3. Deduplicate terms programmatically if DDL is generated from a rules list.

Example fix

// before
CREATE TABLE t (status text CHECK status != 'draft' AND status != 'draft');
// after
CREATE TABLE t (status text CHECK status != 'draft');
Defensive patterns

Strategy: validation

Validate before calling

Set<String> seen = new HashSet<>();
for (var c : neqConstraints) {
    if (!seen.add(c.term())) throw new IllegalArgumentException("Duplicate NEQ term: " + c.term());
}

Try / catch

try {
    session.execute(schemaDdl);
} catch (InvalidRequestException e) {
    if (e.getMessage().contains("duplicate constraint definitions")) {
        log.error("Deduplicate CHECK constraints: {}", e.getMessage());
    } else throw e;
}

Prevention

When it happens

Trigger: CREATE TABLE/ALTER TABLE with two identical NEQ CHECK constraints on the same column, e.g. CHECK status != 'x' AND status != 'x'.

Common situations: Copy-paste mistakes when composing CHECK clauses; schema migrations appending a constraint that already exists; generated DDL emitting duplicates.

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

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