alibaba/nacos · error · IllegalArgumentException

extensions exceeds 32 entries

Error message

extensions exceeds 32 entries

What it means

validateExtensions() caps the extensions map at MAX_EXTENSIONS (32) entries. The cap bounds storage and validation cost for the free-form extension bag. Once the entry count exceeds 32 the whole ext is rejected before any per-entry work.

Source

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

        validateExtensions(resourceExt.getExtensions());
        validateCatalog(resourceExt.getVersionCatalog());
    }
    
    private static void validateProvider(AgentProvider provider) {
        if (provider == null) {
            return;
        }
        validateRequiredCodePointLength(provider.getName(), MAX_PROVIDER_NAME_LENGTH,
            "provider.name");
        validateOptionalAbsoluteUri(provider.getUrl(), "provider.url");
    }
    
    private static void validateExtensions(Map<String, Object> extensions) {
        if (extensions == null) {
            return;
        }
        if (extensions.size() > MAX_EXTENSIONS) {
            throw new IllegalArgumentException(
                "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) {

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Reduce the extensions map to at most 32 keys; move redundant keys into a single nested JSON object under one extension key if you need grouping.
  2. Prefer first-class AgentResourceExt fields (provider, versionCatalog) over extensions for data the model already represents.
  3. Add a client-side size assertion before publishing the agent.

Example fix

// before
Map<String, Object> ext = new HashMap<>();
for (int i = 0; i < 50; i++) ext.put("k" + i, i); // >32 entries
resourceExt.setExtensions(ext);

// after
Map<String, Object> ext = new HashMap<>();
for (int i = 0; i < 32; i++) ext.put("k" + i, i); // keep <= 32
Defensive patterns

Strategy: validation

Validate before calling

if (extensions != null && extensions.size() > 32) {
    throw new AgentExtTooManyEntriesException(extensions.size(), 32);
}

Try / catch

try {
    AgentResourceExtSerializer.serialize(resourceExt);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("extensions exceeds")) {
        // trim or move keys into a single nested object, then retry
        trimExtensions(extensions);
    } else throw e;
}

Prevention

When it happens

Trigger: An agent create/update supplies an extensions map with more than 32 keys via the AI admin API; AgentPersistenceService.serialize propagates the failure on persist.

Common situations: A client dumping many ad-hoc metadata keys (telemetry tags, feature flags) into extensions instead of using dedicated model fields, or a loop that auto-generates extension keys.

Related errors

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