alibaba/nacos · error · IllegalArgumentException

Unable to serialize Agent Version storage descriptor

Error message

Unable to serialize Agent Version storage descriptor

What it means

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.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java:89

        new HashSet<String>(Arrays.asList("provider", "key", "keyFormat", "agentNameCodec",
            "contentDigest", "mediaType", "schemaVersion", "size")));
    
    private AgentVersionStorageDescriptorSerializer() {
    }
    
    /**
     * Validate and serialize an Agent Version storage descriptor.
     *
     * @param descriptor storage descriptor
     * @return JSON stored in {@code ai_resource_version.storage}
     * @throws IllegalArgumentException when the descriptor is invalid
     */
    public static String serialize(AgentVersionStorageDescriptor descriptor) {
        validate(descriptor);
        try {
            return JacksonUtils.toJson(descriptor);
        } catch (NacosSerializationException e) {
            throw new IllegalArgumentException(
                "Unable to serialize Agent Version storage descriptor",
                e);
        }
    }
    
    /**
     * Deserialize and validate an Agent Version storage descriptor.
     *
     * @param json JSON read from {@code ai_resource_version.storage}
     * @return decoded storage descriptor
     * @throws IllegalArgumentException when JSON or descriptor fields are invalid
     */
    public static AgentVersionStorageDescriptor deserialize(String json) {
        validateJsonShape(json);
        final AgentVersionStorageDescriptor descriptor;
        try {
            descriptor = JacksonUtils.toObj(json, AgentVersionStorageDescriptor.class);
        } catch (NacosDeserializationException e) {

View on GitHub (pinned to 9b989acdf1)

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.

Defensive patterns

Strategy: try-catch

Try / catch

try {
    return AgentVersionStorageDescriptorSerializer.serialize(descriptor);
} catch (IllegalArgumentException e) {
    if (e.getCause() instanceof NacosSerializationException) {
        log.error("storage descriptor not serializable", e.getCause());
    }
    throw e;
}

Prevention

Use the standard AgentVersionStorageDescriptor value object without subclassing.
Ensure all descriptor fields are simple types (String, Integer, Long).
Unit-test serialize on representative descriptors.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/3a2cf1e8f067a752. Report an issue: GitHub.