{"record":{"id":"7d76bf6f40a16428","repo":"apache/dubbo","slug":"value-s-for-key-s-in-s-is-not-list","errorCode":null,"errorMessage":"value '%s' for key '%s' in '%s' is not List","messagePattern":"value '(.+?)' for key '(.+?)' in '(.+?)' is not List","errorType":"exception","errorClass":"ClassCastException","httpStatus":null,"severity":"error","filePath":"dubbo-common/src/main/java/org/apache/dubbo/common/json/impl/AbstractJsonUtilImpl.java","lineNumber":55,"sourceCode":"\n            List<String> list = new LinkedList<>();\n            list.add(\"json\");\n            return CollectionUtils.equals(list, toJavaList(toJson(list), String.class));\n        } catch (Throwable t) {\n            return false;\n        }\n    }\n\n    @Override\n    public List<?> getList(Map<String, ?> obj, String key) {\n        assert obj != null;\n        assert key != null;\n        if (!obj.containsKey(key)) {\n            return null;\n        }\n        Object value = obj.get(key);\n        if (!(value instanceof List)) {\n            throw new ClassCastException(String.format(\"value '%s' for key '%s' in '%s' is not List\", value, key, obj));\n        }\n        return (List<?>) value;\n    }\n\n    /**\n     * Gets a list from an object for the given key, and verifies all entries are objects.  If the key\n     * is not present, this returns null.  If the value is not a List or an entry is not an object,\n     * throws an exception.\n     */\n    @Override\n    public List<Map<String, ?>> getListOfObjects(Map<String, ?> obj, String key) {\n        assert obj != null;\n        List<?> list = getList(obj, key);\n        if (list == null) {\n            return null;\n        }\n        return checkObjectList(list);\n    }","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/apache/dubbo/blob/3a3043227f5571d25eb2889de5bca22f2914843b/dubbo-common/src/main/java/org/apache/dubbo/common/json/impl/AbstractJsonUtilImpl.java#L37-L73","documentation":"Thrown by AbstractJsonUtilImpl.getList(Map,String) when obj contains key but its value is not a java.util.List. getList returns null for an absent key, so this exception only fires when the key IS present but the JSON value is a scalar, object, or other non-list type. It is a ClassCastException reflecting a schema/type mismatch between the JSON shape and the expected Java type. Subclasses (the JsonUtil impls) inherit this behavior.","triggerScenarios":"jsonUtil.getList(obj, key) where obj.get(key) exists and is a Map, String, Number, Boolean, or null-reference that is not a List instance. For example JSON {\"items\": {\"a\":1}} with getList(obj, \"items\").","commonSituations":"API contract changed so a field that was an array became a single object (or vice versa); a conditional payload where the field is sometimes a list and sometimes a scalar; downstream service returning an error object instead of the expected array; using getList on a field the schema documents as an object.","solutions":["Confirm the actual runtime type of obj.get(key) and reconcile with the schema — typically the field shape changed upstream.","If the field may legitimately be a scalar or a list, branch on instanceof List before calling getList.","Switch to a more permissive accessor or normalize the JSON to the expected array shape upstream.","Catch ClassCastException and report the offending key/value for triage."],"exampleFix":"// before\nList<?> items = jsonUtil.getList(obj, \"items\");\n// after - tolerate single-or-list\nObject raw = obj.get(\"items\");\nList<?> items = raw instanceof List ? (List<?>) raw : (raw == null ? null : List.of(raw));","handlingStrategy":"type-guard","validationCode":"Object raw = obj.get(key);\nif (raw != null && !(raw instanceof List)) {\n    // field present but not a list; decide policy before calling getList\n    return Collections.emptyList();\n}\nreturn jsonUtil.getList(obj, key);","typeGuard":"private static boolean isListOfMapsOrEmpty(Object value) {\n    return value == null || value instanceof List;\n}","tryCatchPattern":"try {\n    return jsonUtil.getList(obj, key);\n} catch (ClassCastException e) {\n    log.warn(\"expected list at key={}, got value={}\", key, obj.get(key));\n    return null; // or a domain-specific fallback\n}","preventionTips":["Branch on instanceof List before calling getList when the field may vary in shape.","Pin and validate the JSON schema for fields you read with getList.","Treat a single-object-where-list-expected as a schema change and reconcile with the producer."],"tags":["json","type-mismatch","classcast","jsonutil","dubbo-common"],"backgroundTag":null,"analyzedSha":"3a3043227f5571d25eb2889de5bca22f2914843b","analyzedAt":"2026-08-14T00:43:19.853Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}