{"record":{"id":"87ed79ac6cce5d66","repo":"apache/dolphinscheduler","slug":"parse-json-json-to-class-clazz-failed","errorCode":null,"errorMessage":"Parse json: <json> to class: <clazz> failed","messagePattern":"Parse json: <json> to 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":149,"sourceCode":"     * @param json  the string from which the object is to be deserialized\n     * @param clazz the class of T\n     * @param <T>   T\n     * @return an object of type T from the string\n     * classOfT\n     */\n    public static @Nullable <T> T parseObject(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 null;\n        }\n\n        try {\n            return objectMapper.readValue(json, clazz);\n        } catch (Exception e) {\n            throw new IllegalArgumentException(\"Parse json: \" + json + \" to class: \" + clazz.getName() + \" failed\", e);\n        }\n    }\n\n    /**\n     * deserialize\n     *\n     * @param src   byte array\n     * @param clazz class\n     * @param <T>   deserialize type\n     * @return deserialize type\n     */\n    public static <T> T parseObject(byte[] src, Class<T> clazz) {\n        if (src == null) {\n            return null;\n        }\n        String json = new String(src, UTF_8);\n        return parseObject(json, clazz);\n    }","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/utils/JSONUtils.java#L131-L167","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Inspect the cause (e.getCause()) — it is the real Jackson exception naming the exact problem (JsonParseException, MismatchedInputException, etc.).","Validate the string is JSON first (JSONUtils.checkJsonValid) and log the raw payload to see what was actually received.","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).","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>>() {})).","Verify the target class matches the actual payload shape (object vs array vs primitive)."],"exampleFix":"// before\nUser user = JSONUtils.parseObject(response, User.class); // throws on non-JSON error page\n// after\nUser user = null;\nif (JSONUtils.checkJsonValid(response)) {\n    user = JSONUtils.parseObject(response, User.class);\n}","handlingStrategy":"try-catch","validationCode":"if (json == null || !JSONUtils.checkJsonValid(json)) {\n    throw new IllegalArgumentException(\"Payload is not valid JSON: \" + StringUtils.abbreviate(json, 200));\n}","typeGuard":null,"tryCatchPattern":"try {\n    return JSONUtils.parseObject(json, MyDto.class);\n} catch (IllegalArgumentException e) {\n    logger.error(\"Failed to parse json to {}: cause={}, payload={}\",\n            MyDto.class.getSimpleName(), e.getCause(), json, e);\n    return null; // or a default DTO\n}","preventionTips":["Always log e.getCause() — the real Jackson error names the exact field/token problem.","Validate payloads are JSON (not HTML error pages) before parsing external responses.","Keep the consumer class schema in sync with the producer; prefer tolerant mapping (ignore unknowns).","Use the TypeReference overload for generic types instead of raw Class arguments."],"tags":["json","deserialization","jackson"],"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"}