alibaba/nacos · error · IllegalArgumentException

Duplicate tag: {tag}

Error message

Duplicate tag: {tag}

What it means

Thrown by validateTags when the same tag string appears more than once in the Agent's tags list. Tags must be a set, not a list; duplicates would create ambiguous filter and index behavior, so the validator rejects them after enforcing per-tag length.

Source

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

            && !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");
        }
        for (String key : extensions.keySet()) {
            validateRequiredLength(key, MAX_EXTENSION_KEY_LENGTH, "extension key");
        }
    }
    
    private static void validateVersionInfo(AgentVersionInfo versionInfo) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Deduplicate the tags list before submission using a LinkedHashSet to preserve order.
2. Normalize tag casing and trimming before dedup if your source data is inconsistent.
3. Audit tag producers so each source owns a non-overlapping namespace.

Example fix

// before
agent.setTags(Arrays.asList("llm", "chatbot", "llm"));
// after
agent.setTags(new ArrayList<>(new LinkedHashSet<>(Arrays.asList("llm", "chatbot", "llm"))));

static List<String> dedupTags(List<String> tags) {
    if (tags == null) return List.of();
    return new ArrayList<>(new LinkedHashSet<>(tags));
}

static boolean tagsAreUnique(List<String> tags) {
    return tags == null || new HashSet<>(tags).size() == tags.size();
}

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Duplicate tag")) {
        agent.setTags(new ArrayList<>(new LinkedHashSet<>(agent.getTags())));
    }
}

When it happens

Trigger: Submitting a tags list that contains the same string twice (exact case match), e.g. ["llm","chatbot","llm"]. Concatenating tag sources without set normalization.

Common situations: Merging tags from multiple systems that independently tag the same concept; retrying an update where the server already appended a tag the client re-sends; case differences (LLM vs llm) will NOT trigger this since the check is exact-match, but downstream index collisions may still surprise you.

Related errors

• Duplicate Version label: {label}
• Duplicate protocol: {protocol}
• Duplicate CallInterface protocol: {callInterface.protocol}
• Duplicate Endpoint source: {source}
• 20002

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