alibaba/nacos · error · IllegalArgumentException

extensions exceeds entries

Error message

extensions exceeds {MAX_EXTENSIONS} entries

What it means

Thrown by validateExtensions when the Agent.extensions map contains more than MAX_EXTENSIONS (32) entries. Extensions hold arbitrary structured metadata; the entry-count cap bounds serialization cost and index size. The 16 KiB serialized byte limit is enforced separately in the server serializer (AgentResourceExtSerializer), not here.

Solutions

1. Reduce extensions to 32 or fewer keys.
2. Group related values under a single JSON value (object/array) under one key instead of spreading them.
3. Move large or rarely-read metadata out of extensions entirely.
4. After capping keys, also verify the serialized JSON stays under 16 KiB on the server side.

Example fix

// before
extensions.put("timeout", 30); extensions.put("retries", 3); /* ... 33 flat keys */
// after
extensions.put("runtime", Map.of("timeout", 30, "retries", 3)); /* one nested key */

static Map<String, Object> capExtensions(Map<String, Object> ext) {
    if (ext == null) return Map.of();
    if (ext.size() > 32) {
        throw new IllegalArgumentException("extensions exceeds 32 entries");
    }
    return ext;
}

static boolean extensionsWithinLimit(Map<String, Object> ext) {
    return ext == null || ext.size() <= 32;
}

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("extensions exceeds")) { /* nest keys and retry */ }
}

When it happens

Trigger: Registering an Agent whose extensions map has 33+ keys. Dumping an entire descriptor or config object as top-level extension keys instead of nesting it under one key.

Common situations: Flattening a nested config object into individual extension keys; accumulating per-environment overrides as separate keys over time until the cap is exceeded.

Related errors

• callInterfaces must contain 1 to
• must contain 1 to values
• tags exceeds items
• 10000
• 10000

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

Appendix: source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java:379

        }
        if (tags.size() > MAX_TAGS) {
            throw new IllegalArgumentException("tags exceeds " + MAX_TAGS + " items");
        }
        Set<String> uniqueTags = new HashSet<String>();
        for (String tag : tags) {
            validateRequiredLength(tag, MAX_TAG_LENGTH, "tag");
            if (!uniqueTags.add(tag)) {
                throw new IllegalArgumentException("Duplicate tag: " + tag);
            }
        }
    }
    
    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 (String key : extensions.keySet()) {
            validateRequiredLength(key, MAX_EXTENSION_KEY_LENGTH, "extension key");
        }
    }
    
    private static void validateVersionInfo(AgentVersionInfo versionInfo) {
        requireNonNull(versionInfo, "versionInfo");
        if (versionInfo.getEditingVersion() != null) {
            AgentValidationUtils.validateVersion(versionInfo.getEditingVersion());
        }
        if (versionInfo.getReviewingVersion() != null) {
            AgentValidationUtils.validateVersion(versionInfo.getReviewingVersion());
        }
        Integer onlineCount = versionInfo.getOnlineCnt();
        if (onlineCount == null || onlineCount < 0) {
            throw new IllegalArgumentException("onlineCnt must be a non-negative integer");

View on GitHub (pinned to 9b989acdf1)