{"record":{"id":"ef25ef85fe344ee8","repo":"alibaba/nacos","slug":"tags-exceeds-max-tags-items","errorCode":null,"errorMessage":"tags exceeds {MAX_TAGS} items","messagePattern":"tags exceeds (.+?) items","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":363,"sourceCode":"        }\n    }\n    \n    private static void validateVersionStatus(String status) {\n        if (!AiConstants.Agent.VERSION_STATUS_DRAFT.equals(status)\n            && !AiConstants.Agent.VERSION_STATUS_REVIEWING.equals(status)\n            && !AiConstants.Agent.VERSION_STATUS_REVIEWED.equals(status)\n            && !AiConstants.Agent.VERSION_STATUS_ONLINE.equals(status)\n            && !AiConstants.Agent.VERSION_STATUS_OFFLINE.equals(status)) {\n            throw new IllegalArgumentException(\"Invalid Agent Version status: \" + status);\n        }\n    }\n    \n    private static void validateTags(List<String> tags) {\n        if (tags == null) {\n            return;\n        }\n        if (tags.size() > MAX_TAGS) {\n            throw new IllegalArgumentException(\"tags exceeds \" + MAX_TAGS + \" items\");\n        }\n        Set<String> uniqueTags = new HashSet<String>();\n        for (String tag : tags) {\n            validateRequiredLength(tag, MAX_TAG_LENGTH, \"tag\");\n            if (!uniqueTags.add(tag)) {\n                throw new IllegalArgumentException(\"Duplicate tag: \" + tag);\n            }\n        }\n    }\n    \n    private static void validateExtensions(Map<String, Object> extensions) {\n        if (extensions == null) {\n            return;\n        }\n        if (extensions.size() > MAX_EXTENSIONS) {\n            throw new IllegalArgumentException(\n                \"extensions exceeds \" + MAX_EXTENSIONS + \" entries\");\n        }","sourceCodeStart":345,"sourceCodeEnd":381,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L345-L381","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Reduce the tags list to 32 or fewer items.","Deduplicate tags before submission (see error 482) to free up capacity.","Move overflow metadata into the extensions map if it is non-searchable metadata, or into a separate store.","Filter tags to the most operationally meaningful subset at the producer side."],"exampleFix":"// before\nagent.setTags(allMetadataKeys); // 40+ keys\n// after\nagent.setTags(allMetadataKeys.stream().limit(32).toList());","handlingStrategy":"validation","validationCode":"static List<String> capTags(List<String> tags) {\n    if (tags == null) return List.of();\n    if (tags.size() > 32) {\n        throw new IllegalArgumentException(\"tags exceeds 32 items\");\n    }\n    return tags;\n}","typeGuard":"static boolean tagsWithinLimit(List<String> tags) {\n    return tags == null || tags.size() <= 32;\n}","tryCatchPattern":"try {\n    AgentModelValidator.validateAgent(agent);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"tags exceeds\")) { /* trim and retry */ }\n}","preventionTips":["Cap tag generation at the producer to <= 32 items.","Prefer the extensions map for high-cardinality metadata.","Deduplicate before counting so the cap is not wasted on duplicates."],"tags":["ai-agent","validation","capacity-limit","illegal-argument"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}