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 null.

What it means

ConstraintFunction.evaluate runs user constraints on the write path and rejects a null column value before internal evaluation. Technically it triggers when columnValue equals ByteBufferUtil.EMPTY_BYTE_BUFFER, which the code treats as null, throwing ConstraintViolationException because the value cannot satisfy the constraint. This prevents constraints from silently passing on absent data.

Source

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

    {
        this.name = name;
        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. Provide a non-null value for the constrained column in the write.
2. Remove the constraint from the column if nulls must be allowed.
3. Use an IF NOT EXISTS / application-side check to skip writing when the value would be null.

Example fix

// before
stmt.bind(id, null);
// after
stmt.bind(id, name == null ? "default" : name);

if (value == null) throw new IllegalArgumentException("Column " + columnName + " requires a non-null value due to a constraint");

try {
    session.execute(write);
} catch (ConstraintViolationException e) {
    if (e.getMessage().contains("as it is null")) {
        // supply default or skip write
    } else throw e;
}

When it happens

Trigger: INSERT/UPDATE writing a null (or the empty ByteBuffer sentinel) to a column that carries a ConstraintFunction-based constraint; e.g. `INSERT INTO ks.t (id, name) VALUES (uuid(), null)` where name has a LENGTH/JSON/NOT-NULL-style constraint evaluated via evaluate().

Common situations: Application code that binds null for missing fields; partial updates that null out a constrained column; ORMs that serialize missing properties as nulls.

Related errors

• Column value does not satisfy value constraint for column '<
• Value for column '%s' violated %s constraint as it is not a
• Column value does not satisfy value constraint for column '<
• Got null for INSERT JSON values
• %s constraint of relation '%s' is not supported. Only these

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