apache/cassandra · error · ConstraintViolationException

Value for column '%s' violated %s constraint as it is not a

Error message

Value for column '%s' violated %s constraint as it is not a valid JSON.

What it means

JsonConstraint.internalEvaluate validates at write time that the column value is well-formed JSON by decoding the string via JsonUtils.decodeJson; on MarshalException it throws ConstraintViolationException naming the column and the constraint. This guarantees JSON-constrained columns only ever store parseable JSON.

Source

Thrown at src/java/org/apache/cassandra/cql3/constraints/JsonConstraint.java:58

    {
        super(name, args);
    }

    public JsonConstraint(List<String> args)
    {
        this(FUNCTION_NAME, args);
    }

    @Override
    public void internalEvaluate(AbstractType<?> valueType, Operator relationType, String term, ByteBuffer columnValue)
    {
        try
        {
            JsonUtils.decodeJson(valueType.getString(columnValue));
        }
        catch (MarshalException ex)
        {
            throw new ConstraintViolationException(format("Value for column '%s' violated %s constraint as it is not a valid JSON.",
                                                          columnName,
                                                          name));
        }
    }

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

    @Override
    public boolean equals(Object o)
    {
        if (this == o)
            return true;

        if (!(o instanceof JsonConstraint))

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Serialize the value with a proper JSON encoder before writing (e.g. Jackson ObjectMapper.writeValueAsString).
Validate the JSON string client-side before the write (JSON.parse / json.loads).
Remove the JSON constraint if arbitrary text should be stored.

Example fix

// before
String payload = "{'key': 'value'}"; // invalid JSON
// after
String payload = new ObjectMapper().writeValueAsString(Map.of("key", "value")); // {"key":"value"}

Defensive patterns

Strategy: try-catch

Validate before calling

// client-side pre-validation
try { new com.fasterxml.jackson.databind.ObjectMapper().readValue(payload, Object.class); }
catch (Exception e) { throw new IllegalArgumentException("payload is not valid JSON", e); }

Try / catch

try {
    session.execute(write);
} catch (ConstraintViolationException e) {
    if (e.getMessage().contains("not a valid JSON")) {
        // fix serialization or store as plain text
    } else throw e;
}

Prevention

Always serialize with a JSON library, never string concatenation
Remember JSON requires double quotes for keys/strings
Add unit tests asserting payloads parse as JSON before writing

When it happens

Trigger: INSERT/UPDATE writing a string that fails JSON parsing to a column with a JSON constraint — e.g. `payload text ... CHECK JSON()` receiving `{invalid` or plain text like `hello`.

Common situations: Applications storing concatenated/truncated JSON; single quotes vs double quotes (e.g. `{'a': 1}` is invalid JSON); encoding issues; users assuming Cassandra validates JSON automatically without the constraint.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

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