What causes "Parse json: to list of class: failed" in apache/dolphinscheduler?

Check e.getCause() — MismatchedInputException tells you whether it's 'not an array' vs a per-element mapping failure.

apache/dolphinscheduler · error · IllegalArgumentException

Parse json: <json> to list of class: <clazz> failed

Error message

Parse json: <json> to list of class: <clazz> failed

What it means

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.

Source

Thrown at dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/utils/JSONUtils.java:190

     * @param json  json string
     * @param clazz class
     * @param <T>   T
     * @return list
     */
    public static <T> List<T> toList(String json, Class<T> clazz) {
        if (clazz == null) {
            throw new IllegalArgumentException("Class type cannot be null");
        }

        if (Strings.isNullOrEmpty(json)) {
            return Collections.emptyList();
        }

        try {
            CollectionType listType = objectMapper.getTypeFactory().constructCollectionType(ArrayList.class, clazz);
            return objectMapper.readValue(json, listType);
        } catch (Exception e) {
            throw new IllegalArgumentException(
                    "Parse json: " + json + " to list of class: " + clazz.getName() + " failed", e);
        }

    }

    /**
     * check json object valid
     *
     * @param json json
     * @return true if valid
     */
    public static boolean checkJsonValid(String json) {
        return checkJsonValid(json, true);
    }

    public static boolean checkJsonValid(String json, Boolean logFlag) {
        if (Strings.isNullOrEmpty(json)) {
            return false;

View on GitHub (pinned to 02eac45a1b)

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.

Example fix

// before
List<User> users = JSONUtils.toList(response, User.class); // response is {"data":[...]}
// after
List<User> users = JSONUtils.parseObject(response, new TypeReference<List<User>>() {}) != null
        ? JSONUtils.toList(JSONUtils.parseObject(response, Wrapper.class).getData(), User.class)
        : Collections.emptyList();

Defensive patterns

Strategy: try-catch

Validate before calling

String trimmed = json == null ? "" : json.trim();
if (!trimmed.startsWith("[")) {
    throw new IllegalArgumentException("Expected a JSON array for toList, got: " + trimmed.substring(0, Math.min(50, trimmed.length())));
}

Try / catch

try {
    return JSONUtils.toList(json, Item.class);
} catch (IllegalArgumentException e) {
    logger.error("toList failed: {}", e.getCause().toString(), e);
    return Collections.emptyList();
}

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/6a030c652fcce6b9. Report an issue: GitHub.