alibaba/nacos · error · IllegalArgumentException

tags exceeds {MAX_TAGS} items

Error message

tags exceeds {MAX_TAGS} items

What it means

Thrown by validateTags when the Agent's tags list contains more than MAX_TAGS (32) entries. Tags are bounded to keep the Agent resource payload small and the catalog index queryable. This is a hard capacity limit, not a soft warning.

Source

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

        }
    }
    
    private static void validateVersionStatus(String status) {
        if (!AiConstants.Agent.VERSION_STATUS_DRAFT.equals(status)
            && !AiConstants.Agent.VERSION_STATUS_REVIEWING.equals(status)
            && !AiConstants.Agent.VERSION_STATUS_REVIEWED.equals(status)
            && !AiConstants.Agent.VERSION_STATUS_ONLINE.equals(status)
            && !AiConstants.Agent.VERSION_STATUS_OFFLINE.equals(status)) {
            throw new IllegalArgumentException("Invalid Agent Version status: " + status);
        }
    }
    
    private static void validateTags(List<String> tags) {
        if (tags == null) {
            return;
        }
        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");
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Reduce the tags list to 32 or fewer items.
2. Deduplicate tags before submission (see error 482) to free up capacity.
3. Move overflow metadata into the extensions map if it is non-searchable metadata, or into a separate store.
4. Filter tags to the most operationally meaningful subset at the producer side.

Example fix

// before
agent.setTags(allMetadataKeys); // 40+ keys
// after
agent.setTags(allMetadataKeys.stream().limit(32).toList());

static List<String> capTags(List<String> tags) {
    if (tags == null) return List.of();
    if (tags.size() > 32) {
        throw new IllegalArgumentException("tags exceeds 32 items");
    }
    return tags;
}

static boolean tagsWithinLimit(List<String> tags) {
    return tags == null || tags.size() <= 32;
}

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

When it happens

Trigger: Registering or updating an Agent whose tags array has 33+ elements. Bulk-importing Agents from a tagging system that allows hundreds of tags per resource.

Common situations: Auto-generating tags from metadata (one tag per label/key) without capping the result; merging multiple tag sources without dedup before submission; copying full server-side labels into the client-facing tags field.

Related errors

• extensions exceeds {MAX_EXTENSIONS} entries
• {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/ef25ef85fe344ee8. Report an issue: GitHub.