{"record":{"id":"bd93c1bd0ddf85ac","repo":"alibaba/nacos","slug":"unable-to-serialize-agentversioncontent","errorCode":null,"errorMessage":"Unable to serialize AgentVersionContent","messagePattern":"Unable to serialize AgentVersionContent","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionContentSerializer.java","lineNumber":89,"sourceCode":"        \"uri\", \"transport\", \"priority\", \"weight\", \"metadata\"));\n    \n    private AgentVersionContentSerializer() {\n    }\n    \n    /**\n     * Validate and serialize one Agent Version content object.\n     *\n     * @param content Agent Version content\n     * @return immutable serialized storage result\n     * @throws IllegalArgumentException when content is invalid or exceeds the storage limit\n     */\n    public static SerializedContent serialize(AgentVersionContent content) {\n        validate(content);\n        final byte[] bytes;\n        try {\n            bytes = JacksonUtils.toJsonBytes(toStorageProjection(content));\n        } catch (NacosSerializationException e) {\n            throw new IllegalArgumentException(\"Unable to serialize AgentVersionContent\", e);\n        }\n        if (bytes.length > MAX_CONTENT_SIZE) {\n            throw new IllegalArgumentException(\n                \"AgentVersionContent exceeds \" + MAX_CONTENT_SIZE + \" bytes\");\n        }\n        return new SerializedContent(bytes, digest(bytes));\n    }\n    \n    /**\n     * Compute the digest of the exact bytes read from or written to AI Storage.\n     *\n     * @param bytes persisted Agent Version content bytes\n     * @return digest token in {@code sha256:<lowercase hex>} form\n     * @throws IllegalArgumentException when bytes are null or exceed the storage limit\n     */\n    public static String digest(byte[] bytes) {\n        if (bytes == null) {\n            throw new IllegalArgumentException(\"AgentVersionContent bytes must not be null\");","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionContentSerializer.java#L71-L107","documentation":"Thrown by AgentVersionContentSerializer.serialize when Jackson fails to convert the validated AgentVersionContent storage projection to JSON bytes (NacosSerializationException). The content has already passed structural validation, so this indicates a low-level serialization failure — typically a non-serializable value inside the projection or a Jackson misconfiguration.","triggerScenarios":"Calling AgentVersionContentSerializer.serialize(content) (directly or via AgentVersionStorageService.prepare/save) where toStorageProjection produces a Map containing an object Jackson cannot serialize — e.g. a nativeDescriptor that is an opaque object type lacking a serializer, or a circular reference.","commonSituations":"A custom or unexpected type is placed in AgentCallInterface.nativeDescriptor (validated as a non-null JSON value but not type-constrained to JSON-native types). Also possible if JacksonUtils is misconfigured or ObjectMapper is replaced in a fork.","solutions":["Inspect the cause (NacosSerializationException) in the stack trace to find the exact field/value Jackson choked on.","Ensure nativeDescriptor, endpoint metadata, and all projection values are JSON-native types (String, Number, Boolean, Map, List, null).","If you constructed AgentVersionContent manually, build callInterfaces with primitive/JSON-safe descriptor values rather than arbitrary POJOs."],"exampleFix":"// before\ncallInterface.setNativeDescriptor(someOpaquePojo);\n\n// after\ncallInterface.setNativeDescriptor(jacksonSafeMap); // Map<String,Object> of JSON-native values","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    SerializedContent sc = AgentVersionContentSerializer.serialize(content);\n} catch (IllegalArgumentException e) {\n    if (e.getCause() instanceof NacosSerializationException) {\n        log.error(\"AgentVersionContent projection not serializable\", e.getCause());\n        // fix the offending field and retry\n    }\n    throw e;\n}","preventionTips":["Build callInterfaces with JSON-native descriptor values only (Map, List, String, Number, Boolean).","Unit-test serialize() on representative content before integrating a new descriptor shape.","Avoid placing arbitrary POJOs in nativeDescriptor or endpoint metadata."],"tags":["serialization","agent-version","storage","illegal-argument"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}