{"record":{"id":"ae47721b80538cc9","repo":"Tencent/APIJSON","slug":"value-for-key-key-is-not-a-map-valu","errorCode":null,"errorMessage":"Value for key '\" + key + \"' is not a Map: \" + value.getClass().getName()","messagePattern":"Value for key '\" \\+ key \\+ \"' is not a Map: \" \\+ value\\.getClass\\(\\)\\.getName\\(\\)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"APIJSONORM/src/main/java/apijson/JSON.java","lineNumber":340,"sourceCode":"\t/**\n\t * Get a Map value from a Map\n\t * @param map Source map\n\t * @param key The key\n\t * @return The Map value\n\t * @throws IllegalArgumentException If value is not a Map and cannot be converted\n\t */\n\t@SuppressWarnings(\"unchecked\")\n\tpublic static <K, V> Map<K, V> getMap(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 Map) {\n\t\t\treturn (Map<K, V>) value;\n\t\t}\n\n\t\tthrow new IllegalArgumentException(\"Value for key '\" + key + \"' is not a Map: \" + value.getClass().getName());\n\t}\n\n\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;","sourceCodeStart":322,"sourceCodeEnd":358,"githubUrl":"https://github.com/Tencent/APIJSON/blob/5284052872898eddc449a58f629e5c8d588b8e22/APIJSONORM/src/main/java/apijson/JSON.java#L322-L358","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\nMap<String, Object> user = JSON.getMap(request, \"User\"); // throws if \"User\" is a JSONArray\n\n// after\nObject raw = request.get(\"User\");\nMap<String, Object> user = raw instanceof Map ? (Map<String, Object>) raw : null;\nif (user == null && raw instanceof List && !((List<?>) raw).isEmpty()) {\n    user = (Map<String, Object>) ((List<?>) raw).get(0);\n}","handlingStrategy":"type-guard","validationCode":"Object v = request.get(\"User\");\nif (v != null && !(v instanceof Map)) {\n    throw new IllegalStateException(\"Expected JSON object for 'User', got \" + v.getClass().getSimpleName());\n}","typeGuard":"static boolean isJsonObject(Object v) {\n    return v == null || v instanceof Map;\n}","tryCatchPattern":"try {\n    Map<String, Object> user = JSON.getMap(request, \"User\");\n} catch (IllegalArgumentException e) {\n    log.warn(\"'User' is not an object: {}\", e.getMessage());\n    // fall back to single-element array handling or reject the request with 400\n}","preventionTips":["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."],"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"}