{"record":{"id":"8f05aabfba8a82c5","repo":"alibaba/nacos","slug":"must-be-a-json-object","errorCode":null,"errorMessage":"{} must be a JSON object","messagePattern":"(.+?) must be a JSON object","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java","lineNumber":368,"sourceCode":"            validateStringArray(entry, \"protocols\");\n        }\n    }\n    \n    private static void validateStringArray(Map<?, ?> object, String field) {\n        Object value = object.get(field);\n        if (!(value instanceof List)) {\n            throw new IllegalArgumentException(field + \" must be an array\");\n        }\n        for (Object item : (List<?>) value) {\n            if (!(item instanceof String)) {\n                throw new IllegalArgumentException(field + \" must contain only strings\");\n            }\n        }\n    }\n    \n    private static Map<?, ?> requireJsonObject(Object value, String fieldName) {\n        if (!(value instanceof Map)) {\n            throw new IllegalArgumentException(fieldName + \" must be a JSON object\");\n        }\n        return (Map<?, ?>) value;\n    }\n    \n    private static void validateRequiredJsonText(Map<?, ?> object, String field) {\n        if (!(object.get(field) instanceof String)) {\n            throw new IllegalArgumentException(field + \" must be a string\");\n        }\n    }\n    \n    private static void validateOptionalJsonText(Map<?, ?> object, String field) {\n        if (object.containsKey(field) && !(object.get(field) instanceof String)) {\n            throw new IllegalArgumentException(field + \" must be a string\");\n        }\n    }\n    \n    private static void validateJsonInteger(Map<?, ?> object, String field) {\n        Object value = object.get(field);","sourceCodeStart":350,"sourceCodeEnd":386,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java#L350-L386","documentation":"Several nested objects in ai_resource.ext JSON must be JSON objects (Maps). The requireJsonObject helper (line 367) throws this when a value expected to be an object is instead a string, number, array, or null. It guards 'provider', 'extensions', 'versionCatalog', and each 'versionCatalog entry'.","triggerScenarios":"Deserializing ai_resource.ext where, for example, 'provider' is set to a string \"MyOrg\" instead of an object {\"name\":\"MyOrg\"}, or 'versionCatalog' is an array instead of an object.","commonSituations":"Flattening nested objects into scalar values by mistake; schema migration that changed provider from a string to an object; hand-editing JSON and forgetting braces.","solutions":["Wrap the value in curly braces to make it a JSON object with the correct sub-fields.","For 'provider', use {\"name\":\"...\",\"url\":\"...\"} instead of a bare string.","For 'versionCatalog', use {\"onlineVersions\":[...]} instead of an array or string."],"exampleFix":"// before\n\"provider\":\"Acme\"\n// after\n\"provider\":{\"name\":\"Acme\"}","handlingStrategy":"validation","validationCode":"private static void ensureJsonObject(Object value, String field) {\n    if (value != null && !(value instanceof Map)) {\n        throw new IllegalArgumentException(field + \" must be a JSON object\");\n    }\n}","typeGuard":"public static boolean isJsonObject(Object value) {\n    return value instanceof Map;\n}","tryCatchPattern":"try {\n    AgentResourceExtSerializer.deserialize(json);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().endsWith(\"must be a JSON object\")) {\n        // wrap the scalar value in an object or fix the producer\n    }\n    throw e;\n}","preventionTips":["Always use JSON objects ({}) for provider, extensions, and versionCatalog.","Never flatten nested objects into scalar strings.","Test deserialization of all nested object shapes."],"tags":["validation","ai-agent","json-schema","serialization"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}