{"record":{"id":"6a030c652fcce6b9","repo":"apache/dolphinscheduler","slug":"parse-json-json-to-list-of-class-clazz-faile","errorCode":null,"errorMessage":"Parse json: <json> to list of class: <clazz> failed","messagePattern":"Parse json: <json> to list of class: <clazz> failed","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/utils/JSONUtils.java","lineNumber":190,"sourceCode":"     * @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 (clazz == null) {\n            throw new IllegalArgumentException(\"Class type cannot be null\");\n        }\n\n        if (Strings.isNullOrEmpty(json)) {\n            return Collections.emptyList();\n        }\n\n        try {\n            CollectionType listType = objectMapper.getTypeFactory().constructCollectionType(ArrayList.class, clazz);\n            return objectMapper.readValue(json, listType);\n        } catch (Exception e) {\n            throw new IllegalArgumentException(\n                    \"Parse json: \" + json + \" to list of class: \" + clazz.getName() + \" failed\", e);\n        }\n\n    }\n\n    /**\n     * check json object valid\n     *\n     * @param json json\n     * @return true if valid\n     */\n    public static boolean checkJsonValid(String json) {\n        return checkJsonValid(json, true);\n    }\n\n    public static boolean checkJsonValid(String json, Boolean logFlag) {\n        if (Strings.isNullOrEmpty(json)) {\n            return false;","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/utils/JSONUtils.java#L172-L208","documentation":"JSONUtils.toList wraps any Jackson failure while reading a JSON array into List<T> in this IllegalArgumentException, including the offending JSON string and element class name with the underlying cause. It means the string is not parseable as an array of the requested element type.","triggerScenarios":"Passing a JSON object (not array) to toList, malformed/truncated JSON, array elements whose fields don't match the element class (wrong types, incompatible shapes), or an element class Jackson cannot instantiate (abstract type, no default constructor).","commonSituations":"An upstream endpoint changed its response from a JSON array to an object wrapper (e.g. {\"list\": [...]}); a stored JSON blob has a single object instead of an array; consumer's element class is older than the producer's payload; JSON produced by a different serializer with incompatible value types.","solutions":["Check e.getCause() — MismatchedInputException tells you whether it's 'not an array' vs a per-element mapping failure.","Print/inspect the JSON string embedded in the message; confirm it is a top-level JSON array ([...]).","If the payload is an object containing the array, parse the wrapper: parseObject(json, new TypeReference<List<T>>() {}) or a wrapper class with a List<T> field.","Update the element class to match the current payload schema (add missing fields, correct types).","Use try-catch with a fallback empty list when an unparseable payload should not abort the flow."],"exampleFix":"// before\nList<User> users = JSONUtils.toList(response, User.class); // response is {\"data\":[...]}\n// after\nList<User> users = JSONUtils.parseObject(response, new TypeReference<List<User>>() {}) != null\n        ? JSONUtils.toList(JSONUtils.parseObject(response, Wrapper.class).getData(), User.class)\n        : Collections.emptyList();","handlingStrategy":"try-catch","validationCode":"String trimmed = json == null ? \"\" : json.trim();\nif (!trimmed.startsWith(\"[\")) {\n    throw new IllegalArgumentException(\"Expected a JSON array for toList, got: \" + trimmed.substring(0, Math.min(50, trimmed.length())));\n}","typeGuard":null,"tryCatchPattern":"try {\n    return JSONUtils.toList(json, Item.class);\n} catch (IllegalArgumentException e) {\n    logger.error(\"toList failed: {}\", e.getCause().toString(), e);\n    return Collections.emptyList();\n}","preventionTips":["Confirm the payload is a top-level JSON array before calling toList.","Watch for producer schema changes (array -> wrapped object) and add contract tests.","Inspect e.getCause() first; it distinguishes 'not an array' from element mapping failures.","For wrapped arrays, parse the wrapper object and extract the List<T> field instead."],"tags":["json","deserialization","list"],"backgroundTag":"json-unmarshal-failed","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}