{"record":{"id":"2fa2963e59fdc0b4","repo":"chinabugotech/hutool","slug":"unsupported-to-map","errorCode":null,"errorMessage":"Unsupported {} to Map.","messagePattern":"Unsupported (.+?) to Map\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hutool-core/src/main/java/cn/hutool/core/convert/impl/MapConverter.java","lineNumber":79,"sourceCode":"\t\t\t\t\t\t&& Objects.equals(this.keyType, typeArguments[0]) //\n\t\t\t\t\t\t&& Objects.equals(this.valueType, typeArguments[1])) {\n\t\t\t\t\t//对于键值对类型一致的Map对象，不再做转换，直接返回原对象\n\t\t\t\t\treturn (Map) value;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tfinal Class<?> mapClass = TypeUtil.getClass(this.mapType);\n\t\t\tif (null == mapClass || mapClass.isAssignableFrom(AbstractMap.class)) {\n\t\t\t\t// issue#I6YN2A，默认有序\n\t\t\t\tmap =  new LinkedHashMap<>();\n\t\t\t} else{\n\t\t\t\tmap = MapUtil.createMap(mapClass);\n\t\t\t}\n\t\t\tconvertMapToMap((Map) value, map);\n\t\t} else if (BeanUtil.isReadableBean(value.getClass())) {\n\t\t\tif(value.getClass().getName().equals(\"cn.hutool.json.JSONArray\")){\n\t\t\t\t// issue#3795 增加JSONArray转Map错误检查\n\t\t\t\tthrow new UnsupportedOperationException(StrUtil.format(\"Unsupported {} to Map.\", value.getClass().getName()));\n\t\t\t}\n\n\t\t\tmap = BeanUtil.beanToMap(value);\n\t\t\t// 二次转换，转换键值类型\n\t\t\tmap = convertInternal(map);\n\t\t} else {\n\t\t\tthrow new UnsupportedOperationException(StrUtil.format(\"Unsupported toMap value type: {}\", value.getClass().getName()));\n\t\t}\n\t\treturn map;\n\t}\n\n\t/**\n\t * Map转Map\n\t *\n\t * @param srcMap 源Map\n\t * @param targetMap 目标Map\n\t */\n\tprivate void convertMapToMap(Map<?, ?> srcMap, Map<Object, Object> targetMap) {","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/chinabugotech/hutool/blob/8870454b2a0c29cc6ffd31dcf5667c8ceb2fc442/hutool-core/src/main/java/cn/hutool/core/convert/impl/MapConverter.java#L61-L97","documentation":"MapConverter explicitly rejects a cn.hutool.json.JSONArray being converted to a Map (issue#3795): a JSON array is a sequence, not a key/value structure, so it throws UnsupportedOperationException naming the class.","triggerScenarios":"Calling Convert.convert(jsonArray, Map.class) (or a Map generic) where jsonArray is an instance of cn.hutool.json.JSONArray, and JSONArray is detected as a readable bean.","commonSituations":"Generic JSON deserialization that does not first discriminate array vs object; misconfiguring a target type from JSON payload inspection.","solutions":["Detect the source is a JSONArray and convert to a List instead, or to the array element type.","Use JSONArray.toBean(targetType) with the correct target type (List or bean).","Wrap the array in a single-entry map if a Map truly is required (index -> element)."],"exampleFix":"// before\nMap m = Convert.convert(jsonArray, Map.class);\n\n// after - target the right shape\nList list = Convert.convert(jsonArray, List.class);\n// or\nList<Item> items = jsonArray.toList(Item.class);","handlingStrategy":"type-guard","validationCode":"if (value.getClass().getName().equals(\"cn.hutool.json.JSONArray\")) {\n    throw new IllegalArgumentException(\"JSONArray cannot become a Map; target a List instead\");\n}\nConvert.convert(value, Map.class);","typeGuard":"!(\"cn.hutool.json.JSONArray\".equals(value.getClass().getName()))","tryCatchPattern":"try {\n    return Convert.convert(value, Map.class);\n} catch (UnsupportedOperationException e) {\n    if (e.getMessage().contains(\"to Map.\")) {\n        return Convert.convert(value, List.class); // correct shape for a JSON array\n    }\n    throw e;\n}","preventionTips":["Discriminate JSON object vs array before choosing Map vs List target.","Use JSONArray.toList / toBean with the correct element type."],"tags":["convert","map","json","type-mismatch"],"backgroundTag":null,"analyzedSha":"8870454b2a0c29cc6ffd31dcf5667c8ceb2fc442","analyzedAt":"2026-08-14T04:01:12.892Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}