chinabugotech/hutool · error · UnsupportedOperationException

Unsupported {} to Map.

Error message

Unsupported {} to Map.

What it means

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.

Source

Thrown at hutool-core/src/main/java/cn/hutool/core/convert/impl/MapConverter.java:79

						&& Objects.equals(this.keyType, typeArguments[0]) //
						&& Objects.equals(this.valueType, typeArguments[1])) {
					//对于键值对类型一致的Map对象，不再做转换，直接返回原对象
					return (Map) value;
				}
			}

			final Class<?> mapClass = TypeUtil.getClass(this.mapType);
			if (null == mapClass || mapClass.isAssignableFrom(AbstractMap.class)) {
				// issue#I6YN2A，默认有序
				map =  new LinkedHashMap<>();
			} else{
				map = MapUtil.createMap(mapClass);
			}
			convertMapToMap((Map) value, map);
		} else if (BeanUtil.isReadableBean(value.getClass())) {
			if(value.getClass().getName().equals("cn.hutool.json.JSONArray")){
				// issue#3795 增加JSONArray转Map错误检查
				throw new UnsupportedOperationException(StrUtil.format("Unsupported {} to Map.", value.getClass().getName()));
			}

			map = BeanUtil.beanToMap(value);
			// 二次转换，转换键值类型
			map = convertInternal(map);
		} else {
			throw new UnsupportedOperationException(StrUtil.format("Unsupported toMap value type: {}", value.getClass().getName()));
		}
		return map;
	}

	/**
	 * Map转Map
	 *
	 * @param srcMap 源Map
	 * @param targetMap 目标Map
	 */
	private void convertMapToMap(Map<?, ?> srcMap, Map<Object, Object> targetMap) {

View on GitHub (pinned to 8870454b2a)

Solutions

1. Detect the source is a JSONArray and convert to a List instead, or to the array element type.
2. Use JSONArray.toBean(targetType) with the correct target type (List or bean).
3. Wrap the array in a single-entry map if a Map truly is required (index -> element).

Example fix

// before
Map m = Convert.convert(jsonArray, Map.class);

// after - target the right shape
List list = Convert.convert(jsonArray, List.class);
// or
List<Item> items = jsonArray.toList(Item.class);

if (value.getClass().getName().equals("cn.hutool.json.JSONArray")) {
    throw new IllegalArgumentException("JSONArray cannot become a Map; target a List instead");
}
Convert.convert(value, Map.class);

!("cn.hutool.json.JSONArray".equals(value.getClass().getName()))

try {
    return Convert.convert(value, Map.class);
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("to Map.")) {
        return Convert.convert(value, List.class); // correct shape for a JSON array
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: Generic JSON deserialization that does not first discriminate array vs object; misconfiguring a target type from JSON payload inspection.

Related errors

• Unsupported to map from [{}] of type: {}
• Unsupported toMap value type: {}
• Unsupported to map from [{}] of type: {}
• Default value [{}]({}) is not the instance of [{}]
• Unsupported source type: {}

AI-assisted analysis of chinabugotech/hutool@8870454b2a (2026-08-14). Data as JSON: /api/errors/2fa2963e59fdc0b4. Report an issue: GitHub.