{"record":{"id":"3a2cf1e8f067a752","repo":"alibaba/nacos","slug":"unable-to-serialize-agent-version-storage-descript","errorCode":null,"errorMessage":"Unable to serialize Agent Version storage descriptor","messagePattern":"Unable to serialize Agent Version storage descriptor","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java","lineNumber":89,"sourceCode":"        new HashSet<String>(Arrays.asList(\"provider\", \"key\", \"keyFormat\", \"agentNameCodec\",\n            \"contentDigest\", \"mediaType\", \"schemaVersion\", \"size\")));\n    \n    private AgentVersionStorageDescriptorSerializer() {\n    }\n    \n    /**\n     * Validate and serialize an Agent Version storage descriptor.\n     *\n     * @param descriptor storage descriptor\n     * @return JSON stored in {@code ai_resource_version.storage}\n     * @throws IllegalArgumentException when the descriptor is invalid\n     */\n    public static String serialize(AgentVersionStorageDescriptor descriptor) {\n        validate(descriptor);\n        try {\n            return JacksonUtils.toJson(descriptor);\n        } catch (NacosSerializationException e) {\n            throw new IllegalArgumentException(\n                \"Unable to serialize Agent Version storage descriptor\",\n                e);\n        }\n    }\n    \n    /**\n     * Deserialize and validate an Agent Version storage descriptor.\n     *\n     * @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) {","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java#L71-L107","documentation":"Thrown by AgentVersionStorageDescriptorSerializer.serialize when Jackson fails to convert the validated AgentVersionStorageDescriptor to a JSON string (NacosSerializationException). The descriptor has passed field validation, so this indicates a low-level serialization failure on the descriptor object itself.","triggerScenarios":"Calling serialize(descriptor) where the descriptor object, though field-valid, contains a value Jackson cannot render — e.g. a non-serializable custom type in an extension field, or a circular reference.","commonSituations":"A subclass or fork of AgentVersionStorageDescriptor adds a non-serializable field, or the descriptor is constructed with an unexpected value type that passed validation but breaks Jackson. Rare since the descriptor is a flat value object.","solutions":["Inspect the NacosSerializationException cause for the failing field.","Ensure the descriptor is a plain AgentVersionStorageDescriptor with standard field types (String, Integer, Long).","Avoid subclassing or injecting non-serializable members into the descriptor."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    return AgentVersionStorageDescriptorSerializer.serialize(descriptor);\n} catch (IllegalArgumentException e) {\n    if (e.getCause() instanceof NacosSerializationException) {\n        log.error(\"storage descriptor not serializable\", e.getCause());\n    }\n    throw e;\n}","preventionTips":["Use the standard AgentVersionStorageDescriptor value object without subclassing.","Ensure all descriptor fields are simple types (String, Integer, Long).","Unit-test serialize on representative descriptors."],"tags":["serialization","agent-version","storage-descriptor","illegal-argument"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}