{"record":{"id":"0eb030cff7076be8","repo":"apache/cassandra","slug":"expected-a-list-representation-of-a-tuple-but-got","errorCode":null,"errorMessage":"Expected a list representation of a tuple, but got a %s: %s","messagePattern":"Expected a list representation of a tuple, but got a (.+?): (.+?)","errorType":"validation","errorClass":"MarshalException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/marshal/TupleType.java","lineNumber":495,"sourceCode":"            else\n            {\n                AbstractType<?> type = type(i);\n                fieldString = ESCAPED_COLON_PAT.matcher(fieldString).replaceAll(COLON);\n                fieldString = ESCAPED_AT_PAT.matcher(fieldString).replaceAll(AT);\n                fields.add(type.fromString(fieldString));\n            }\n        }\n        return pack(fields);\n    }\n\n    @Override\n    public Term fromJSONObject(Object parsed) throws MarshalException\n    {\n        if (parsed instanceof String)\n            parsed = JsonUtils.decodeJson((String) parsed);\n\n        if (!(parsed instanceof List))\n            throw new MarshalException(String.format(\n                    \"Expected a list representation of a tuple, but got a %s: %s\", parsed.getClass().getSimpleName(), parsed));\n\n        List<?> list = (List<?>) parsed;\n\n        if (list.size() > types.size())\n            throw new MarshalException(String.format(\"Tuple contains extra items (expected %s): %s\", types.size(), parsed));\n        else if (types.size() > list.size())\n            throw new MarshalException(String.format(\"Tuple is missing items (expected %s): %s\", types.size(), parsed));\n\n        List<Term> terms = new ArrayList<>(list.size());\n        Iterator<AbstractType<?>> typeIterator = types.iterator();\n        for (Object element : list)\n        {\n            if (element == null)\n            {\n                typeIterator.next();\n                terms.add(Constants.NULL_VALUE);\n            }","sourceCodeStart":477,"sourceCodeEnd":513,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/marshal/TupleType.java#L477-L513","documentation":"TupleType.fromJSONObject converts a parsed JSON value into a tuple Term. The JSON must be a list whose elements map to the tuple's fields. If the parsed object is not a List (e.g. a string, map, or number), this MarshalException is thrown with the value's Java class name and contents.","triggerScenarios":"Inserting JSON where the tuple column is given an object/map instead of an array (e.g. {\"t\": {\"a\":1}} instead of {\"t\": [1,2]}); passing a JSON-encoded string that decodes to a non-list to fromJSONObject.","commonSituations":"Application JSON serializers emitting maps for tuples; double-encoded JSON strings (a string containing JSON) where decodeJson produces a scalar; cqlsh INSERT JSON with a malformed tuple field.","solutions":["Send the tuple as a JSON array: [elem1, elem2, ...]","Fix double-encoding by passing the parsed JSON structure, not a JSON string containing JSON","Check the client serializer's mapping for tuple columns","Validate the payload shape before INSERT JSON"],"exampleFix":"// before\n{\"t\": {\"0\": 1, \"1\": 2}}\n// after\n{\"t\": [1, 2]}","handlingStrategy":"type-guard","validationCode":"Object parsed = JsonUtils.decodeJson(json);\nif (!(parsed instanceof List)) throw new IllegalArgumentException(\"tuple JSON must be an array\");","typeGuard":"boolean isTupleJson(Object parsed) { return parsed instanceof List; }","tryCatchPattern":"try {\n    Term t = tupleType.fromJSONObject(parsed);\n} catch (MarshalException e) {\n    throw new IllegalArgumentException(\"tuple JSON shape invalid: \" + e.getMessage());\n}","preventionTips":["Serialize tuple columns as JSON arrays, never maps or strings","Avoid double-encoding JSON strings for tuple fields","Test INSERT JSON payloads against the schema in CI"],"tags":["json","tuple","validation"],"backgroundTag":"json-unmarshal-failed","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}