{"record":{"id":"c1e1f8fc08a23bae","repo":"Tencent/APIJSON","slug":"value-for-key-key-is-not-a-list-val","errorCode":null,"errorMessage":"Value for key '\" + key + \"' is not a List: \" + value.getClass().getName()","messagePattern":"Value for key '\" \\+ key \\+ \"' is not a List: \" \\+ value\\.getClass\\(\\)\\.getName\\(\\)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"APIJSONORM/src/main/java/apijson/JSON.java","lineNumber":361,"sourceCode":"\t/**\n\t * Get a List value from a Map\n\t * @param map Source map\n\t * @param key The key\n\t * @return The List value\n\t * @throws IllegalArgumentException If value is not a List and cannot be converted\n\t */\n\t@SuppressWarnings(\"unchecked\")\n\tpublic static <T> List<T> getList(Map<String, Object> map, String key) throws IllegalArgumentException {\n\t\tObject value = map == null || key == null ? null : map.get(key);\n\t\tif (value == null) {\n\t\t\treturn null;\n\t\t}\n\n\t\tif (value instanceof List) {\n\t\t\treturn (List<T>) value;\n\t\t}\n\n\t\tthrow new IllegalArgumentException(\"Value for key '\" + key + \"' is not a List: \" + value.getClass().getName());\n\t}\n\n\t/**\n\t * Get an int value from a Map\n\t * @param map Source map\n\t * @param key The key\n\t * @return The int value\n\t * @throws IllegalArgumentException If value cannot be converted to int\n\t */\n\tpublic static Integer getInteger(Map<String, Object> map, String key) throws IllegalArgumentException {\n\t\tObject value = map == null || key == null ? null : map.get(key);\n\t\tif (value == null) {\n\t\t\treturn null;\n\t\t}\n\n\t\tif (value instanceof Number) {\n\t\t\treturn ((Number) value).intValue();\n\t\t}","sourceCodeStart":343,"sourceCodeEnd":379,"githubUrl":"https://github.com/Tencent/APIJSON/blob/5284052872898eddc449a58f629e5c8d588b8e22/APIJSONORM/src/main/java/apijson/JSON.java#L343-L379","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Log the raw value and its class at that key to confirm what the sender actually produced.","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.","If the value is a delimited String, split it yourself: Arrays.asList(str.split(\",\")) instead of relying on getList.","Check the key spelling against APIJSON array conventions (commonly the trailing \"[]\") — the object form often lives under the un-suffixed key."],"exampleFix":"// before\nList<Object> comments = JSON.getList(request, \"Comment[]\"); // throws when only one Map was sent\n\n// after\nObject raw = request.get(\"Comment[]\");\nList<Object> comments = raw instanceof List ? (List<Object>) raw\n        : (raw instanceof Map ? Collections.singletonList(raw) : null);","handlingStrategy":"type-guard","validationCode":"Object v = request.get(\"Comment[]\");\nif (v != null && !(v instanceof List)) {\n    throw new IllegalStateException(\"Expected JSON array for 'Comment[]', got \" + v.getClass().getSimpleName());\n}","typeGuard":"static boolean isJsonArray(Object v) {\n    return v == null || v instanceof List;\n}","tryCatchPattern":"try {\n    List<Object> comments = JSON.getList(request, \"Comment[]\");\n} catch (IllegalArgumentException e) {\n    log.warn(\"'Comment[]' is not an array: {}\", e.getMessage());\n    // normalize single-object-to-list, or return 400 to the caller\n}","preventionTips":["Follow APIJSON's naming convention: suffix array-valued request keys with \"[]\" consistently on both ends.","Make list endpoints always return arrays, even for a single item.","Assert payload shapes in contract tests so object/array drift fails CI, not production."],"tags":["json","type-conversion","apijson","schema-mismatch"],"backgroundTag":null,"analyzedSha":"5284052872898eddc449a58f629e5c8d588b8e22","analyzedAt":"2026-08-14T15:15:29.577Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}