{"record":{"id":"ff7c8162b8b10612","repo":"alibaba/nacos","slug":"agent-version-storage-descriptor-json-must-not-be","errorCode":null,"errorMessage":"Agent Version storage descriptor JSON must not be empty","messagePattern":"Agent Version storage descriptor JSON must not be empty","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java","lineNumber":116,"sourceCode":"     * @param json JSON read from {@code ai_resource_version.storage}\n     * @return decoded storage descriptor\n     * @throws IllegalArgumentException when JSON or descriptor fields are invalid\n     */\n    public static AgentVersionStorageDescriptor deserialize(String json) {\n        validateJsonShape(json);\n        final AgentVersionStorageDescriptor descriptor;\n        try {\n            descriptor = JacksonUtils.toObj(json, AgentVersionStorageDescriptor.class);\n        } catch (NacosDeserializationException e) {\n            throw new IllegalArgumentException(\"Invalid Agent Version storage descriptor\", e);\n        }\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            }","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java#L98-L134","documentation":"First guard inside deserialize()/validateJsonShape. It fires when the input string is null or empty (\"\"), meaning the storage descriptor has no content at all. This is a fail-fast check before any JSON parsing is attempted.","triggerScenarios":"AgentVersionStorageDescriptorSerializer.deserialize(null) or deserialize(\"\"). Reached when row.getStorage() returns null/empty, i.e. a version row with no storage descriptor (incomplete insert, draft never persisted, migration gap).","commonSituations":"A draft Agent Version row created before content was saved; a DB migration that left the storage column NULL; a custom persistence layer returning null; calling deserialize on an unsaved entity.","solutions":["Ensure the Agent Version content was saved via AgentVersionStorageService.save(...) so the storage column is populated","If the row is stale or orphaned, delete it or re-publish the version","Verify AgentPersistenceService.claimVersion writes the storage column atomically with the row insert"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"String storage = row.getStorage();\nif (storage == null || storage.isEmpty()) {\n    throw new NacosException(NacosException.SERVER_ERROR,\n        \"Agent Version has no storage descriptor: \" + agentName + '@' + version);\n}\nAgentVersionStorageDescriptor d =\n    AgentVersionStorageDescriptorSerializer.deserialize(storage);","typeGuard":null,"tryCatchPattern":"try {\n    AgentVersionStorageDescriptorSerializer.deserialize(json);\n} catch (IllegalArgumentException e) {\n    // handle missing/empty storage\n}","preventionTips":["Reject null/empty storage before calling deserialize","Ensure AgentVersionStorageService.save always populates the storage column atomically with the version row"],"tags":["java","nacos","ai-agent","validation","storage-descriptor","null-input"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}