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>' as it is empty.

What it means

ConstraintFunction.evaluate rejects a column value that is an empty ByteBuffer when the value type declares isEmptyValueMeaningless() (e.g. int, uuid types whose zero-length encoding is meaningless). It throws ConstraintViolationException so constrained columns cannot hold such empty values. This runs on every write evaluated against the constraint.

Source

Thrown at src/java/org/apache/cassandra/cql3/constraints/ConstraintFunction.java:74

        this.rawArgs = args;
        this.args = unquote(args);
    }

    public List<String> arguments()
    {
        return args;
    }

    /**
     * Method that performs the actual condition test, executed during the write path.
     * It the test is not successful, it throws a {@link ConstraintViolationException}.
     */
    public void evaluate(AbstractType<?> valueType, Operator relationType, String term, ByteBuffer columnValue) throws ConstraintViolationException
    {
        if (columnValue == ByteBufferUtil.EMPTY_BYTE_BUFFER)
            throw new ConstraintViolationException("Column value does not satisfy value constraint for column '" + columnName + "' as it is null.");
        else if (valueType.isEmptyValueMeaningless() && columnValue.capacity() == 0)
            throw new ConstraintViolationException("Column value does not satisfy value constraint for column '" + columnName + "' as it is empty.");

        internalEvaluate(valueType, relationType, term, columnValue);
    }

    /**
     * Internal evaluation method, by default called from {@link ConstraintFunction#evaluate(AbstractType, Operator, String, ByteBuffer)}.
     * {@code columnValue} is by default guaranteed to not represent CQL value of 'null'.
     */
    protected abstract void internalEvaluate(AbstractType<?> valueType, Operator relationType, String term, ByteBuffer columnValue);

    /**
     * Used mostly for unary functions which do not expect any relation type nor term.
     */
    public void evaluate(AbstractType<?> valueType, ByteBuffer columnValue) throws ConstraintViolationException
    {
        evaluate(valueType, null, null, columnValue);
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Write a valid non-empty value (or a real default) instead of an empty buffer.
  2. Remove the constraint if empty values must be allowed.
  3. Ensure the client driver serializes null as null (not an empty buffer) for the column type.

Example fix

// before
boundValues[1] = ByteBuffer.allocate(0);
// after
boundValues[1] = value == null ? null : Int32Type.instance.decompose(value);
Defensive patterns

Strategy: try-catch

Validate before calling

if (value != null && value.remaining() == 0 && valueType.isEmptyValueMeaningless())
    throw new IllegalArgumentException("Empty buffer is invalid for constrained column " + columnName);

Type guard

static boolean isValidBoundValue(ByteBuffer v) { return v == null || v.remaining() > 0; }

Try / catch

try {
    session.execute(write);
} catch (ConstraintViolationException e) {
    if (e.getMessage().contains("as it is empty")) {
        // replace with a real value or null
    } else throw e;
}

Prevention

When it happens

Trigger: Writing a zero-capacity/empty byte buffer to a constrained column whose AbstractType reports isEmptyValueMeaningless() == true — e.g. binding an empty buffer for an int or timestamp column with a constraint, then evaluate() is invoked during the write path.

Common situations: Driver serialization bugs producing 0-length buffers for null-adjacent values; manually constructed ByteBuffers in tooling; migrating data where empty values were previously tolerated.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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