alibaba/nacos · error · IllegalArgumentException

Agent extensions exceeds {} bytes

Error message

Agent extensions exceeds {} bytes

What it means

After successful re-serialization, validateExtensions() enforces MAX_EXTENSIONS_SIZE (16384 bytes / 16 KiB) on the UTF-8 byte length of the extensions map. This is the hard storage budget for the free-form extension bag, independent of the 32-entry count cap.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java:166

                "extensions exceeds " + MAX_EXTENSIONS + " entries");
        }
        for (Map.Entry<?, ?> entry : extensions.entrySet()) {
            if (!(entry.getKey() instanceof String)) {
                throw new IllegalArgumentException(
                    "Agent extensions contains a non-string JSON object key");
            }
            String key = (String) entry.getKey();
            validateRequiredCodePointLength(key, MAX_EXTENSION_KEY_LENGTH, "extension key");
            validateJsonValue(entry.getValue(), "extension " + entry.getKey());
        }
        final byte[] bytes;
        try {
            bytes = JacksonUtils.toJsonBytes(extensions);
        } catch (NacosSerializationException e) {
            throw new IllegalArgumentException("Unable to serialize Agent extensions", e);
        }
        if (bytes.length > MAX_EXTENSIONS_SIZE) {
            throw new IllegalArgumentException(
                "Agent extensions exceeds " + MAX_EXTENSIONS_SIZE + " bytes");
        }
    }
    
    private static void validateJsonValue(Object value, String fieldName) {
        if (value == null || value instanceof String || value instanceof Boolean
            || value instanceof Byte || value instanceof Short || value instanceof Integer
            || value instanceof Long) {
            return;
        }
        if (value instanceof Float) {
            if (!Float.isFinite((Float) value)) {
                throw new IllegalArgumentException(fieldName + " must be a finite JSON number");
            }
            return;
        }
        if (value instanceof Double) {
            if (!Double.isFinite((Double) value)) {

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Trim the extensions payload below 16 KiB; store large blobs out-of-band (e.g. an object store URL) and keep only a reference in extensions.
  2. Compress or shorten verbose keys/values.
  3. Measure with JacksonUtils.toJsonBytes(extensions).length before publishing.

Example fix

// before
ext.put("badge", base64ImageOf14Kb); // pushes total over 16384

// after
ext.put("badgeUrl", "https://cdn.example.com/agent.png");
Defensive patterns

Strategy: validation

Validate before calling

int size = com.alibaba.nacos.common.utils.JacksonUtils.toJsonBytes(extensions).length;
if (size > AgentResourceExtSerializer.MAX_EXTENSIONS_SIZE) {
    throw new AgentExtTooLargeException(size, AgentResourceExtSerializer.MAX_EXTENSIONS_SIZE);
}

Try / catch

try {
    AgentResourceExtSerializer.serialize(resourceExt);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Agent extensions exceeds")) {
        // move large blobs to external storage and keep only a URL reference
        externalizeLargeExtensions(extensions);
    } else throw e;
}

Prevention

When it happens

Trigger: An agent create/update whose extensions serialize to more than 16384 bytes (e.g. large embedded base64 blobs, big nested structures, or many moderately-sized values).

Common situations: Embedding an icon/logo as base64 in extensions, pasting large config documents, or accumulating verbose metadata.

Related errors

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