alibaba/nacos · error · IllegalArgumentException

Unable to serialize AgentVersionContent

Error message

Unable to serialize AgentVersionContent

What it means

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.

Source

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

        "uri", "transport", "priority", "weight", "metadata"));
    
    private AgentVersionContentSerializer() {
    }
    
    /**
     * Validate and serialize one Agent Version content object.
     *
     * @param content Agent Version content
     * @return immutable serialized storage result
     * @throws IllegalArgumentException when content is invalid or exceeds the storage limit
     */
    public static SerializedContent serialize(AgentVersionContent content) {
        validate(content);
        final byte[] bytes;
        try {
            bytes = JacksonUtils.toJsonBytes(toStorageProjection(content));
        } catch (NacosSerializationException e) {
            throw new IllegalArgumentException("Unable to serialize AgentVersionContent", e);
        }
        if (bytes.length > MAX_CONTENT_SIZE) {
            throw new IllegalArgumentException(
                "AgentVersionContent exceeds " + MAX_CONTENT_SIZE + " bytes");
        }
        return new SerializedContent(bytes, digest(bytes));
    }
    
    /**
     * Compute the digest of the exact bytes read from or written to AI Storage.
     *
     * @param bytes persisted Agent Version content bytes
     * @return digest token in {@code sha256:<lowercase hex>} form
     * @throws IllegalArgumentException when bytes are null or exceed the storage limit
     */
    public static String digest(byte[] bytes) {
        if (bytes == null) {
            throw new IllegalArgumentException("AgentVersionContent bytes must not be null");

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Inspect the cause (NacosSerializationException) in the stack trace to find the exact field/value Jackson choked on.
  2. Ensure nativeDescriptor, endpoint metadata, and all projection values are JSON-native types (String, Number, Boolean, Map, List, null).
  3. If you constructed AgentVersionContent manually, build callInterfaces with primitive/JSON-safe descriptor values rather than arbitrary POJOs.

Example fix

// before
callInterface.setNativeDescriptor(someOpaquePojo);

// after
callInterface.setNativeDescriptor(jacksonSafeMap); // Map<String,Object> of JSON-native values
Defensive patterns

Strategy: try-catch

Try / catch

try {
    SerializedContent sc = AgentVersionContentSerializer.serialize(content);
} catch (IllegalArgumentException e) {
    if (e.getCause() instanceof NacosSerializationException) {
        log.error("AgentVersionContent projection not serializable", e.getCause());
        // fix the offending field and retry
    }
    throw e;
}

Prevention

When it happens

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

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

Related errors

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