apache/cassandra · error · ConstraintViolationException

Column value does not satisfy value constraint for column '<

Error message

Column value does not satisfy value constraint for column '<columnName>'. It has a length of <valueLength> and it should be <relationType> <term>

What it means

LengthConstraint.internalEvaluate compares the actual byte length of the written value against the constraint's numeric term using the given operator (e.g. >=, <=) and throws ConstraintViolationException when the relation is not satisfied. The message reports the value's length, the required operator, and the required bound.

Source

Thrown at src/java/org/apache/cassandra/cql3/constraints/LengthConstraint.java:57

        super(name, args);
    }

    public LengthConstraint(List<String> args)
    {
        this(NAME, args);
    }

    @Override
    public void internalEvaluate(AbstractType<?> valueType, Operator relationType, String term, ByteBuffer columnValue)
    {
        int valueLength = getValueLength(columnValue, valueType);
        int sizeConstraint = Integer.parseInt(term);

        ByteBuffer leftOperand = ByteBufferUtil.bytes(valueLength);
        ByteBuffer rightOperand = ByteBufferUtil.bytes(sizeConstraint);

        if (!relationType.isSatisfiedBy(Int32Type.instance, leftOperand, rightOperand))
            throw new ConstraintViolationException("Column value does not satisfy value constraint for column '" + columnName + "'. "
                                                   + "It has a length of " + valueLength + " and it should be "
                                                   + relationType + ' ' + term);
    }

    @Override
    public List<Operator> getSupportedOperators()
    {
        return DEFAULT_FUNCTION_OPERATORS;
    }

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

    private int getValueLength(ByteBuffer value, AbstractType<?> valueType)
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Shorten or lengthen the written value so its byte length satisfies the constraint.
  2. Relax the constraint bounds in the schema (ALTER TABLE) to accommodate real data sizes.
  3. Count bytes (not chars) in client-side validation to mirror the constraint.
  4. Verify the term in the constraint is the intended integer bound.

Example fix

// before (constraint LENGTH() >= 8)
stmt.bindString("password", "abc");
// after
String pw = "abc";
if (pw.getBytes(StandardCharsets.UTF_8).length < 8) pw = padOrReject(pw);
stmt.bindString("password", pw);
Defensive patterns

Strategy: validation

Validate before calling

int len = value.getBytes(StandardCharsets.UTF_8).length;
if (!relationSatisfied(len, minOrMax))
    throw new IllegalArgumentException("length " + len + " violates constraint " + relationType + " " + term);

Try / catch

try {
    session.execute(write);
} catch (ConstraintViolationException e) {
    if (e.getMessage().contains("It has a length of")) {
        // truncate/extend value or relax the constraint
    } else throw e;
}

Prevention

When it happens

Trigger: INSERT/UPDATE where the value length (in bytes) fails the declared length relation, e.g. a column constrained to `LENGTH() >= 5` receiving a 3-byte string, or `LENGTH() <= 10` receiving a 20-character string. The term must parse as an int.

Common situations: Users assuming LENGTH counts characters for multi-byte UTF-8 text (it counts bytes); password/username policies not enforced client-side; ALTERing constraints after data of other sizes exists (new writes then fail).

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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