apache/cassandra · error · MarshalException

Invalid null element in list

Error message

Invalid null element in list

What it means

While converting each element of the JSON array into a Term, fromJSONObject rejects JSON null elements with MarshalException, since vectors cannot contain null elements (same rule as the binary validation path).

Source

Thrown at src/java/org/apache/cassandra/db/marshal/VectorType.java:329

    @Override
    public Term fromJSONObject(Object parsed) throws MarshalException
    {
        if (parsed instanceof String)
            parsed = JsonUtils.decodeJson((String) parsed);

        if (!(parsed instanceof List))
            throw new MarshalException(String.format(
            "Expected a list, but got a %s: %s", parsed.getClass().getSimpleName(), parsed));

        List<?> list = (List<?>) parsed;
        if (list.size() != dimension)
            throw new MarshalException(String.format("List had incorrect size: expected %d but given %d; %s", dimension, list.size(), list));
        List<Term> terms = new ArrayList<>(list.size());
        for (Object element : list)
        {
            if (element == null)
                throw new MarshalException("Invalid null element in list");
            terms.add(elementType.fromJSONObject(element));
        }

        return new MultiElements.DelayedValue(this, terms);
    }

    @Override
    public boolean equals(Object o)
    {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        VectorType<?> that = (VectorType<?>) o;
        return dimension == that.dimension && Objects.equals(elementType, that.elementType);
    }

    @Override
    public int hashCode()
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Remove nulls from the JSON array or substitute default values
  2. Reject/repair such records upstream before insert
  3. Coerce nulls to a sentinel like 0.0 if semantically acceptable

Example fix

// before
json = "[0.1, null, 0.3]";
// after
json = "[0.1, 0.0, 0.3]";
Defensive patterns

Strategy: validation

Validate before calling

boolean containsNull = list.stream().anyMatch(Objects::isNull);
if (containsNull) throw new IllegalArgumentException("null element in vector JSON");

Type guard

static <T> boolean noNulls(List<T> l) { return l.stream().noneMatch(Objects::isNull); }

Try / catch

try { term = vt.fromJSONObject(list); } catch (MarshalException e) { /* null element: reject record */ }

Prevention

When it happens

Trigger: JSON insert containing nulls inside the vector array, e.g. [1.0, null, 3.0] for a vector column.

Common situations: Data pipelines with missing embeddings emitting null placeholders; user-supplied JSON with nulls; ETL joins producing nulls for missing values.

Related errors

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