apache/dolphinscheduler · error · IllegalArgumentException

Parse json: <json> to type: <type> failed

Error message

Parse json: <json> to type: <type> failed

What it means

JSONUtils.parseObject(String, TypeReference<T>) wraps any Jackson readValue failure in this IllegalArgumentException carrying the JSON string, the resolved TypeReference type, and the cause. It means the JSON could not be read into the requested generic type.

Source

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

     *
     * @param json json string
     * @param type type reference
     * @param <T>
     * @return return parse object
     */
    public static <T> T parseObject(String json, TypeReference<T> type) {
        if (Strings.isNullOrEmpty(json)) {
            return null;
        }

        if (type == null) {
            throw new IllegalArgumentException("Type reference cannot be null");
        }

        try {
            return objectMapper.readValue(json, type);
        } catch (Exception e) {
            throw new IllegalArgumentException("Parse json: " + json + " to type: " + type.getType() + " failed", e);
        }
    }

    /**
     * object to json string
     *
     * @param object object
     * @return json string
     */
    public static String toJsonString(Object object) {
        try {
            return objectMapper.writeValueAsString(object);
        } catch (Exception e) {
            throw new RuntimeException("Object json deserialization exception.", e);
        }
    }

    public static String toPrettyJsonString(Object object) {

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Read e.getCause() — Jackson's message pinpoints the offending path/field (JsonMappingException with path reference).
  2. Verify the TypeReference exactly mirrors the payload structure, including wrappers ({"data":[...]} needs a wrapper type).
  3. For polymorphic payloads, ensure type info was embedded at serialization time (@JsonTypeInfo) or use the correct concrete type.
  4. Ensure the TypeReference is created as an anonymous subclass so the generic type is retained (new TypeReference<List<T>>() {}), never via a raw new TypeReference<T>().
  5. Wrap in try-catch with a fallback/default value when the payload may legitimately be unreadable.

Example fix

// before
TypeReference<Map<String, User>> t = new TypeReference<Map<String, User>>() {};
Map<String, User> m = JSONUtils.parseObject(json, t); // json is actually a bare array
// after
if (json.trim().startsWith("[")) {
    List<User> list = JSONUtils.parseObject(json, new TypeReference<List<User>>() {});
} else {
    Map<String, User> m = JSONUtils.parseObject(json, new TypeReference<Map<String, User>>() {});
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (json == null || json.trim().isEmpty()) {
    return null; // parseObject returns null for empty input anyway
}

Try / catch

try {
    return JSONUtils.parseObject(json, new TypeReference<Map<String, Object>>() {});
} catch (IllegalArgumentException e) {
    logger.error("Json -> {} failed: {}, payload={}",
            type.getType(), e.getCause(), json, e);
    throw new DataParseException(e.getCause());
}

Prevention

When it happens

Trigger: Malformed JSON; JSON whose shape differs from the TypeReference (object where a List was expected, nested field type mismatches, nulls where primitives are declared); using raw/erased types so Jackson cannot see generics (new TypeReference doesn't help if built via reflection with a missing type parameter).

Common situations: Generic types erased by passing Map<String, X> through layers that lost the parameter; an API response wrapped differently than the declared TypeReference; polymorphic payloads serialized without type info; nested collections with mismatched element 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/40cf4a80fb8221e7. Report an issue: GitHub.