apache/cassandra · error · MarshalException

List had incorrect size: expected

Error message

List had incorrect size: expected %d but given %d; %s

What it means

fromJSONObject verifies that the JSON array's length equals the vector type's declared dimension. A list of any other size is rejected with MarshalException reporting expected vs given size, since vector columns have fixed dimension.

Solutions

1. Provide a JSON array with exactly the declared number of elements
2. ALTER TABLE ... ALTER column TYPE vector<...> to the new dimension if the data legitimately changed size
3. Validate array length against the schema dimension before inserting

Example fix

// before
// vector<float, 3> column
json = "[0.1, 0.2]";
// after
json = "[0.1, 0.2, 0.3]"; // 3 elements

if (list.size() != dimension)
    throw new IllegalArgumentException("expected " + dimension + " elements, got " + list.size());

try { term = vt.fromJSONObject(list); } catch (MarshalException e) { /* size mismatch: repair or reject record */ }

When it happens

Trigger: Inserting via JSON with an array whose length differs from the column's declared dimension, e.g. vector<float, 3> given [1.0, 2.0] in a JSON insert path.

Common situations: Embedding model dimension changed but the schema (or data pipeline) did not; hand-written JSON payloads with missing/extra elements; ETL jobs truncating arrays.

Understand the failure class

Background: Tensor shape mismatch errors ("must have shape", "expected shape ... got ..."): when tensor dimensions disagree with what an op or layer was told to expect — this error's family across 6 libraries.

Related errors

• Attempted to add float vector of dimension
• Expected a list, but got a
• Invalid null element in list
• Required elements, but saw
• cannot parse ' ' as hex bytes

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

Appendix: source

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

            sb.append(elementType.toJSONString(split.get(i), accessor, protocolVersion));
        }
        sb.append(']');
        return sb.toString();
    }

    @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);

View on GitHub (pinned to 88fd0f6a0e)