apache/cassandra · error · MarshalException

Invalid null element in list

Error message

Invalid null element in list

What it means

While converting a JSON array for a list column, each element is recursively converted via the element type's fromJSONObject. Cassandra does not allow null elements inside collections, so a JSON null element immediately raises MarshalException.

Source

Thrown at src/java/org/apache/cassandra/db/marshal/ListType.java:249

        return bbs;
    }

    @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;
        List<Term> terms = new ArrayList<>(list.size());
        for (Object element : list)
        {
            if (element == null)
                throw new MarshalException("Invalid null element in list");
            terms.add(elements.fromJSONObject(element));
        }

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

    public ByteBuffer getSliceFromSerialized(ByteBuffer collection, ByteBuffer from, ByteBuffer to)
    {
        // We don't support slicing on lists so we don't need that function
        throw new UnsupportedOperationException();
    }

    @Override
    public String toJSONString(ByteBuffer buffer, ProtocolVersion protocolVersion)
    {
        return setOrListToJsonString(buffer, elements, protocolVersion);
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove null entries from the array before sending.
2. Replace null with a sentinel/default value if the schema requires fixed positions.
3. Filter nulls in application code or the producer's serialization layer.

Example fix

// before
{"scores": [1, null, 3]}
// after
{"scores": [1, 3]}

boolean hasNull = ((List<?>) value).stream().anyMatch(Objects::isNull);
if (hasNull) throw new IllegalArgumentException("Cassandra collections do not allow null elements");

try { term = listType.fromJSONObject(parsed); } catch (MarshalException e) { log.warn("List contained nulls"); parsed = stripNulls(parsed); }

When it happens

Trigger: fromJSONObject called with a JSON array containing null, e.g. {"tags": ["a", null]}.

Common situations: JavaScript clients with undefined values serialized as null; sparse data merged into arrays; deserialization frameworks that fill missing entries with null.

Related errors

• null is not supported inside collections
• Expected a list, but got a %s: %s
• Invalid null key in map
• Invalid null value in map
• Invalid null element in set

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