What causes "Value for key '" + key + "' is not a Map: " + value.getClass().getName()" in Tencent/APIJSON?

Inspect the actual value first: log request.get(key).getClass() and the raw value to see what really arrived at that key.

Tencent/APIJSON · error · IllegalArgumentException

Value for key '" + key + "' is not a Map: " + value.getClass

Error message

Value for key '" + key + "' is not a Map: " + value.getClass().getName()

What it means

Thrown by apijson.JSON.getMap(Map, String) (APIJSONORM/src/main/java/apijson/JSON.java:340) when the value stored at the given key is non-null but is not a java.util.Map. APIJSON models JSON objects as Map and refuses to silently coerce other types (String, Number, List, Boolean), so a structural mismatch is reported as IllegalArgumentException naming the offending key and runtime class.

Source

Thrown at APIJSONORM/src/main/java/apijson/JSON.java:340

	/**
	 * Get a Map value from a Map
	 * @param map Source map
	 * @param key The key
	 * @return The Map value
	 * @throws IllegalArgumentException If value is not a Map and cannot be converted
	 */
	@SuppressWarnings("unchecked")
	public static <K, V> Map<K, V> getMap(Map<String, Object> map, String key) throws IllegalArgumentException {
		Object value = map == null || key == null ? null : map.get(key);
		if (value == null) {
			return null;
		}

		if (value instanceof Map) {
			return (Map<K, V>) value;
		}

		throw new IllegalArgumentException("Value for key '" + key + "' is not a Map: " + value.getClass().getName());
	}

	/**
	 * Get a List value from a Map
	 * @param map Source map
	 * @param key The key
	 * @return The List value
	 * @throws IllegalArgumentException If value is not a List and cannot be converted
	 */
	@SuppressWarnings("unchecked")
	public static <T> List<T> getList(Map<String, Object> map, String key) throws IllegalArgumentException {
		Object value = map == null || key == null ? null : map.get(key);
		if (value == null) {
			return null;
		}

		if (value instanceof List) {
			return (List<T>) value;

View on GitHub (pinned to 5284052872)

Solutions

Inspect the actual value first: log request.get(key).getClass() and the raw value to see what really arrived at that key.
If the payload nests the object inside an array, take the element: JSON.getMap(...) on (Map) JSON.getList(request, key).get(0), or fix the sender to send {...} not [{...}].
If the value is a JSON object serialized as a String, parse it before/instead: JSON.parseObject((String) value) or use apijson's parser entry points so nested objects are materialized as Map.
Align with the real schema: if the field is genuinely a list, switch to JSON.getList(map, key) and adapt the consuming code.

Example fix

// before
Map<String, Object> user = JSON.getMap(request, "User"); // throws if "User" is a JSONArray

// after
Object raw = request.get("User");
Map<String, Object> user = raw instanceof Map ? (Map<String, Object>) raw : null;
if (user == null && raw instanceof List && !((List<?>) raw).isEmpty()) {
    user = (Map<String, Object>) ((List<?>) raw).get(0);
}

Defensive patterns

Strategy: type-guard

Validate before calling

Object v = request.get("User");
if (v != null && !(v instanceof Map)) {
    throw new IllegalStateException("Expected JSON object for 'User', got " + v.getClass().getSimpleName());
}

Type guard

static boolean isJsonObject(Object v) {
    return v == null || v instanceof Map;
}

Try / catch

try {
    Map<String, Object> user = JSON.getMap(request, "User");
} catch (IllegalArgumentException e) {
    log.warn("'User' is not an object: {}", e.getMessage());
    // fall back to single-element array handling or reject the request with 400
}

Prevention

Define the request schema once (shared constants/types) so producers and consumers agree which keys are objects vs arrays.
Validate incoming payloads at the boundary with a schema check before passing maps to JSON getters.
Log the raw payload class per key when onboarding a new client integration to catch shape drift early.

When it happens

Trigger: Calling JSON.getMap(request, "User") when request.get("User") returns a JSONArray/List (e.g. the client sent [{...}] instead of {...}); calling it on a value that is a serialized JSON string like "{\"id\":1}" that was never parsed; passing a key whose value another layer replaced with a scalar (id, name).

Common situations: Upstream API changed a field from a single object to an array (or vice versa) without a version bump; request payloads copy-pasted from curl examples where the object got wrapped in [ ]; JSON strings stored in config/DB and passed to the map without JSON.parseObject; mixing JSON parsers (fastjson JSONObject vs plain HashMap) so the expected nested object arrives as a different container.

Related errors

AI-assisted analysis of Tencent/APIJSON@5284052872 (2026-08-14). Data as JSON: /api/errors/ae47721b80538cc9. Report an issue: GitHub.