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 should be <relationType> <term>

What it means

Thrown by OctetLengthConstraint.internalEvaluate when a column's byte length fails a declared LENGTH-based column constraint. Cassandra evaluates column constraints on every INSERT/UPDATE, and this exception surfaces as a ConstraintViolationException when the value's length does not satisfy the configured relation (e.g. LENGTH(col) >= 5).

Source

Thrown at src/java/org/apache/cassandra/cql3/constraints/OctetLengthConstraint.java:51

{
    private static final List<AbstractType<?>> SUPPORTED_TYPES = List.of(BytesType.instance, UTF8Type.instance, AsciiType.instance);

    public OctetLengthConstraint(List<String> args)
    {
        super("OCTET_LENGTH", args);
    }

    @Override
    public void internalEvaluate(AbstractType<?> valueType, Operator relationType, String term, ByteBuffer columnValue)
    {
        int valueLength = columnValue.remaining();
        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 should be "
                                                   + relationType + ' ' + term);
    }

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

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

    @Override
    public boolean equals(Object o)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Adjust the inserted value so its byte length satisfies the constraint (check LENGTH in cqlsh before writing).
  2. ALTER the table to drop or relax the constraint if the length rule is wrong (DROP CONSTRAINT / re-add with correct term).
  3. Validate value length in the application before issuing the write, accounting for UTF-8 byte length rather than character count.

Example fix

// before: INSERT INTO t (id, name) VALUES (1, 'ab'); -- fails LENGTH(name) >= 5
// after
INSERT INTO t (id, name) VALUES (1, 'abcde');
Defensive patterns

Strategy: validation

Validate before calling

// Java: check byte length before writing
int len = value.getBytes(StandardCharsets.UTF_8).length; // or ByteBuffer.remaining()
if (len < 5) throw new IllegalArgumentException("name must be >= 5 bytes, got " + len);

Try / catch

catch (ConstraintViolationException | InvalidRequestException e) { log.warn("length constraint violated: {}", e.getMessage()); /* surface to caller */ }

Prevention

When it happens

Trigger: INSERT/UPDATE writes a value to a column with an octet-length constraint whose actual byte length does not satisfy the constraint's relationType against the term (e.g. constraint LENGTH(col) > 10 but value is 3 bytes).

Common situations: Schema declares min/max length constraints but application code sends short, empty, or oversized strings/blobs; multi-byte UTF-8 characters inflate byte length beyond the expected character count; truncation or padding changes upstream.

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/837c64192fff0aec. Report an issue: GitHub.