{"record":{"id":"425fb620b458f280","repo":"alibaba/nacos","slug":"agent-version-storage-descriptor-must-be-a-json-ob","errorCode":null,"errorMessage":"Agent Version storage descriptor must be a JSON object","messagePattern":"Agent Version storage descriptor must be a JSON object","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java","lineNumber":127,"sourceCode":"        }\n        validate(descriptor);\n        return descriptor;\n    }\n    \n    private static void validateJsonShape(String json) {\n        if (json == null || json.isEmpty()) {\n            throw new IllegalArgumentException(\n                \"Agent Version storage descriptor JSON must not be empty\");\n        }\n        validateSingleJsonValue(json);\n        final Map<?, ?> root;\n        try {\n            root = JacksonUtils.toObj(json, Map.class);\n        } catch (NacosDeserializationException e) {\n            throw new IllegalArgumentException(\"Invalid Agent Version storage descriptor\", e);\n        }\n        if (root == null) {\n            throw new IllegalArgumentException(\n                \"Agent Version storage descriptor must be a JSON object\");\n        }\n        for (Object fieldName : root.keySet()) {\n            if (!FIELDS.contains(fieldName)) {\n                throw new IllegalArgumentException(\n                    \"Unknown Agent Version storage descriptor field: \" + fieldName);\n            }\n        }\n        validateJsonText(root, \"provider\", false);\n        validateJsonText(root, \"key\", false);\n        validateJsonText(root, \"keyFormat\", true);\n        validateJsonText(root, \"agentNameCodec\", true);\n        validateJsonText(root, \"contentDigest\", false);\n        validateJsonText(root, \"mediaType\", false);\n        validateJsonInteger(root, \"schemaVersion\");\n        validateJsonInteger(root, \"size\");\n    }\n    ","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java#L109-L145","documentation":"After parsing the input as a Map, the root is null. This happens specifically for the JSON literal `null` (the four characters n-u-l-l), which is a single valid JSON value but not an object. The serializer requires a JSON object.","triggerScenarios":"AgentVersionStorageDescriptorSerializer.deserialize(\"null\"). The storage column literally contains the text `null`.","commonSituations":"A write path that stored String.valueOf(null) or a JSON null token instead of omitting the field; an ORM mapping bug; a bad manual edit that typed the word null into the column.","solutions":["Replace the literal 'null' text with a proper descriptor JSON object","Re-publish the Agent Version so the server writes a valid descriptor","Audit the write path that produced the literal null string (look for String.valueOf or careless null serialization)"],"exampleFix":"// before (stored column literally contains)\nnull\n// after\n{\"provider\":\"nacos_config\",\"key\":\"namespace:agent-version:agent__Agent__1.0.0.json\",...}","handlingStrategy":"try-catch","validationCode":"if (json != null && \"null\".equals(json.trim())) {\n    throw new NacosException(NacosException.SERVER_ERROR,\n        \"Agent Version storage descriptor is the literal 'null'\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    AgentVersionStorageDescriptorSerializer.deserialize(json);\n} catch (IllegalArgumentException e) {\n    throw new NacosException(NacosException.SERVER_ERROR, \"Corrupt storage descriptor\", e);\n}","preventionTips":["Never store String.valueOf(null) or a JSON null token in the storage column","Audit write paths for careless null serialization"],"tags":["java","nacos","ai-agent","validation","json","storage-descriptor","data-corruption"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}