Tencent/APIJSON · error · IllegalArgumentException

Value for key '" + key + "' is not a List: " + value.getClas

Error message

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

What it means

Thrown by apijson.JSON.getList(Map, String) (APIJSONORM/src/main/java/apijson/JSON.java:361) when the value at the given key is non-null but is not a java.util.List. APIJSON models JSON arrays as List and will not coerce a Map, String, or Number into one, so any structural mismatch fails fast with the key and the actual runtime class in the message.

Source

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

	/**
	 * 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;
		}

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

	/**
	 * Get an int value from a Map
	 * @param map Source map
	 * @param key The key
	 * @return The int value
	 * @throws IllegalArgumentException If value cannot be converted to int
	 */
	public static Integer getInteger(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 Number) {
			return ((Number) value).intValue();
		}

View on GitHub (pinned to 5284052872)

Solutions

  1. Log the raw value and its class at that key to confirm what the sender actually produced.
  2. If a single object legitimately means a one-element list, normalize it before calling: wrap the Map in Collections.singletonList(map) or fix the producer to always emit an array.
  3. If the value is a delimited String, split it yourself: Arrays.asList(str.split(",")) instead of relying on getList.
  4. Check the key spelling against APIJSON array conventions (commonly the trailing "[]") — the object form often lives under the un-suffixed key.

Example fix

// before
List<Object> comments = JSON.getList(request, "Comment[]"); // throws when only one Map was sent

// after
Object raw = request.get("Comment[]");
List<Object> comments = raw instanceof List ? (List<Object>) raw
        : (raw instanceof Map ? Collections.singletonList(raw) : null);
Defensive patterns

Strategy: type-guard

Validate before calling

Object v = request.get("Comment[]");
if (v != null && !(v instanceof List)) {
    throw new IllegalStateException("Expected JSON array for 'Comment[]', got " + v.getClass().getSimpleName());
}

Type guard

static boolean isJsonArray(Object v) {
    return v == null || v instanceof List;
}

Try / catch

try {
    List<Object> comments = JSON.getList(request, "Comment[]");
} catch (IllegalArgumentException e) {
    log.warn("'Comment[]' is not an array: {}", e.getMessage());
    // normalize single-object-to-list, or return 400 to the caller
}

Prevention

When it happens

Trigger: Calling JSON.getList(request, "Comment[]") or JSON.getList(response, "list") when the stored value is a single Map/JSONObject (sender sent one object instead of an array); the value is a comma-separated String like "1,2,3"; the value is a Number (e.g. a count) because the wrong key was used.

Common situations: REST endpoints that return an object when the collection has one item and an array otherwise; clients hand-building params and forgetting the [ ] wrapper APIJSON uses for array-valued request keys; switching the wrong key name (e.g. "Comment" vs "Comment[]"); serialized array strings from config that were never parsed.

Related errors

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