alibaba/nacos · error · IllegalArgumentException

AgentVersionContent exceeds {MAX_CONTENT_SIZE} bytes

Error message

AgentVersionContent exceeds {MAX_CONTENT_SIZE} bytes

What it means

Thrown by AgentVersionContentSerializer.serialize when the serialized JSON byte length of the AgentVersionContent storage projection exceeds MAX_CONTENT_SIZE (1 MiB = 1048576 bytes). This is a hard storage ceiling enforced after serialization so the limit applies to exact persisted bytes, not the in-memory model.

Source

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

    }
    
    /**
     * 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");
        }
        if (bytes.length > MAX_CONTENT_SIZE) {
            throw new IllegalArgumentException(

View on GitHub (pinned to 9b989acdf1)

Solutions

Reduce the size of nativeDescriptor payloads — store large specs externally and reference by URI instead of embedding.
Trim metadata maps and remove unused declared endpoints.
If the limit is genuinely too low for your use case, raise MAX_CONTENT_SIZE in AgentVersionContentSerializer and update the corresponding spec, but this is a storage-contract change requiring maintainer discussion.

Example fix

// before
callInterface.setNativeDescriptor(hugeOpenApiJsonString); // >1 MiB

// after
callInterface.setNativeDescriptor(referenceObjectWithUri); // small JSON object pointing to external spec

Defensive patterns

Strategy: validation

Validate before calling

SerializedContent probe = AgentVersionContentSerializer.serialize(content);
// serialize itself enforces the limit; to pre-check without serializing,
estimate JSON size before building large descriptors and reject early.

Try / catch

try {
    return AgentVersionStorageService.save(ns, agent, version, content);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("exceeds")) {
        return ApiErrors.payloadTooLarge("Agent Version content exceeds 1 MiB");
    }
    throw e;
}

Prevention

Keep nativeDescriptor under ~900 KiB to leave room for the JSON envelope.
Store large specs externally and embed only a reference.
Run a size check in CI on sample agent descriptors.

When it happens

Trigger: Publishing or updating an Agent Version whose callInterfaces contain very large nativeDescriptor blobs, many declared endpoints, or large metadata maps such that the canonical JSON projection crosses 1 MiB.

Common situations: An agent descriptor (e.g. a full MCP tool catalog or OpenAPI spec embedded in nativeDescriptor) is too large. Also when a draft accumulates many call interfaces or endpoints near the 16-interface / 64-endpoint limits with bulky metadata.

Related errors

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