apache/dolphinscheduler · error · IllegalArgumentException

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

Error message

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

What it means

JSONUtils.parseObject(String, Class<T>) wraps any exception from Jackson's objectMapper.readValue in this IllegalArgumentException, embedding both the original JSON and the target class name plus the cause. It means the string could not be deserialized into the requested type — usually malformed JSON or JSON whose structure/fields do not match the class.

Source

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

     * @param json  the string from which the object is to be deserialized
     * @param clazz the class of T
     * @param <T>   T
     * @return an object of type T from the string
     * classOfT
     */
    public static @Nullable <T> T parseObject(String json, Class<T> clazz) {
        if (clazz == null) {
            throw new IllegalArgumentException("Class type cannot be null");
        }

        if (Strings.isNullOrEmpty(json)) {
            return null;
        }

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

    /**
     * deserialize
     *
     * @param src   byte array
     * @param clazz class
     * @param <T>   deserialize type
     * @return deserialize type
     */
    public static <T> T parseObject(byte[] src, Class<T> clazz) {
        if (src == null) {
            return null;
        }
        String json = new String(src, UTF_8);
        return parseObject(json, clazz);
    }

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Inspect the cause (e.getCause()) — it is the real Jackson exception naming the exact problem (JsonParseException, MismatchedInputException, etc.).
  2. Validate the string is JSON first (JSONUtils.checkJsonValid) and log the raw payload to see what was actually received.
  3. Enable/verify FAIL_ON_UNKNOWN_PROPERTIES is disabled if unknown fields from a newer producer are the problem (JSONUtils configures this already for its mapper — use it rather than a raw ObjectMapper).
  4. If the payload can legitimately be non-JSON (error pages, empty bodies), guard with try-catch and return null/a default, or switch to the TypeReference overload with the correct target type (e.g. List<X>.class won't work — use parseObject(json, new TypeReference<List<X>>() {})).
  5. Verify the target class matches the actual payload shape (object vs array vs primitive).

Example fix

// before
User user = JSONUtils.parseObject(response, User.class); // throws on non-JSON error page
// after
User user = null;
if (JSONUtils.checkJsonValid(response)) {
    user = JSONUtils.parseObject(response, User.class);
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (json == null || !JSONUtils.checkJsonValid(json)) {
    throw new IllegalArgumentException("Payload is not valid JSON: " + StringUtils.abbreviate(json, 200));
}

Try / catch

try {
    return JSONUtils.parseObject(json, MyDto.class);
} catch (IllegalArgumentException e) {
    logger.error("Failed to parse json to {}: cause={}, payload={}",
            MyDto.class.getSimpleName(), e.getCause(), json, e);
    return null; // or a default DTO
}

Prevention

When it happens

Trigger: Calling parseObject with invalid JSON (trailing characters, unquoted keys, truncated response), or valid JSON that doesn't match the target class (array passed to a POJO, wrong field types that Jackson cannot coerce, unknown structure), or a class whose type Jackson cannot construct (no default constructor, unsupported generic Object target).

Common situations: Parsing an upstream API/HTTP response that returned an HTML error page instead of JSON; a stored JSON column whose schema drifted from the current Java class; version mismatch where a producer serialized a newer shape than the consumer's class; someone logged a stack trace only to find JsonParseException hidden as the cause.

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/87ed79ac6cce5d66. Report an issue: GitHub.