alibaba/nacos · error · IllegalArgumentException

extensions exceeds {MAX_EXTENSIONS} 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.

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)

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

• tags exceeds {MAX_TAGS} items
• {fieldName} must contain 1 to {MAX_CALL_INTERFACES} values
• callInterfaces must contain 1 to {MAX_CALL_INTERFACES} items
• 20002
• 10000

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