{"record":{"id":"48452ec2ca40a3b7","repo":"apache/seatunnel","slug":"json-parse-list-exception","errorCode":null,"errorMessage":"Json parse list exception!","messagePattern":"Json parse list exception!","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"seatunnel-common/src/main/java/org/apache/seatunnel/common/utils/JsonUtils.java","lineNumber":157,"sourceCode":"    /**\n     * json to list\n     *\n     * @param json json string\n     * @param clazz class\n     * @param <T> T\n     * @return list\n     */\n    public static <T> List<T> toList(String json, Class<T> clazz) {\n        if (StringUtils.isEmpty(json)) {\n            return Collections.emptyList();\n        }\n\n        try {\n            CollectionType listType =\n                    OBJECT_MAPPER.getTypeFactory().constructCollectionType(ArrayList.class, clazz);\n            return OBJECT_MAPPER.readValue(json, listType);\n        } catch (Exception e) {\n            throw new RuntimeException(\"Json parse list exception!\", e);\n        }\n    }\n\n    /**\n     * Method for finding a JSON Object field with specified name in this node or its child nodes,\n     * and returning value it has. If no matching field is found in this node or its descendants,\n     * returns null.\n     *\n     * @param jsonNode json node\n     * @param fieldName Name of field to look for\n     * @return Value of first matching node found, if any; null if none\n     */\n    public static String findValue(JsonNode jsonNode, String fieldName) {\n        JsonNode node = jsonNode.findValue(fieldName);\n\n        if (node == null) {\n            return null;\n        }","sourceCodeStart":139,"sourceCodeEnd":175,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-common/src/main/java/org/apache/seatunnel/common/utils/JsonUtils.java#L139-L175","documentation":"Signals that Jackson failed to deserialize the input string into a List<T> inside JsonUtils.toList. The method accepts any json string plus a target element class, so the exception fires when the payload is not valid JSON or its top-level structure is not a JSON array (or elements do not match the expected type); the original Jackson exception is wrapped in a generic RuntimeException with only a sentinel message, so the true cause (e.g. mismatched JSON structure) is only visible in the wrapped cause.","triggerScenarios":"Calling JsonUtils.toList(json, clazz) with input that is not a JSON array (a plain object, scalar, or invalid JSON), or elements that cannot be bound to the element class.","commonSituations":"A service returns a single object instead of a list after a version change, JSON contains objects where the element class expects other types, whitespace/malformed JSON from logs or files.","solutions":["Inspect the cause: 'Cannot deserialize ... out of START_OBJECT' means the input is not an array","Confirm the payload is a JSON array starting with '['; if a single object, wrap it or use parseObject","Verify element class field types match the JSON","Pre-validate with a quick readTree check that the node is an array"],"exampleFix":"// before\nList<Item> items = JsonUtils.toList(singleObjectJson, Item.class); // not an array\n// after\nList<Item> items = JsonUtils.toList(\"[\" + singleObjectJson + \"]\", Item.class);","handlingStrategy":"try-catch","validationCode":"boolean isJsonArray(String s) { return s != null && s.trim().startsWith(\"[\"); }","typeGuard":null,"tryCatchPattern":"try {\n    List<Item> items = JsonUtils.toList(json, Item.class);\n} catch (RuntimeException e) {\n    log.error(\"list parse failed: {}\", e.getCause());\n    items = Collections.emptyList();\n}","preventionTips":["Verify the endpoint always returns an array; handle single-object envelopes separately","Keep element DTO field types in sync with the producer schema","Unit-test list parsing against real payload samples"],"tags":["jackson","deserialization","runtime-exception"],"backgroundTag":"json-unmarshal-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}