{"record":{"id":"94231222fe1e6f3f","repo":"alibaba/nacos","slug":"extensions-exceeds-max-extensions-entries","errorCode":null,"errorMessage":"extensions exceeds {MAX_EXTENSIONS} entries","messagePattern":"extensions exceeds (.+?) entries","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":379,"sourceCode":"        }\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        }\n        for (String key : extensions.keySet()) {\n            validateRequiredLength(key, MAX_EXTENSION_KEY_LENGTH, \"extension key\");\n        }\n    }\n    \n    private static void validateVersionInfo(AgentVersionInfo versionInfo) {\n        requireNonNull(versionInfo, \"versionInfo\");\n        if (versionInfo.getEditingVersion() != null) {\n            AgentValidationUtils.validateVersion(versionInfo.getEditingVersion());\n        }\n        if (versionInfo.getReviewingVersion() != null) {\n            AgentValidationUtils.validateVersion(versionInfo.getReviewingVersion());\n        }\n        Integer onlineCount = versionInfo.getOnlineCnt();\n        if (onlineCount == null || onlineCount < 0) {\n            throw new IllegalArgumentException(\"onlineCnt must be a non-negative integer\");","sourceCodeStart":361,"sourceCodeEnd":397,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L361-L397","documentation":"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.","triggerScenarios":"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.","commonSituations":"Flattening a nested config object into individual extension keys; accumulating per-environment overrides as separate keys over time until the cap is exceeded.","solutions":["Reduce extensions to 32 or fewer keys.","Group related values under a single JSON value (object/array) under one key instead of spreading them.","Move large or rarely-read metadata out of extensions entirely.","After capping keys, also verify the serialized JSON stays under 16 KiB on the server side."],"exampleFix":"// before\nextensions.put(\"timeout\", 30); extensions.put(\"retries\", 3); /* ... 33 flat keys */\n// after\nextensions.put(\"runtime\", Map.of(\"timeout\", 30, \"retries\", 3)); /* one nested key */","handlingStrategy":"validation","validationCode":"static Map<String, Object> capExtensions(Map<String, Object> ext) {\n    if (ext == null) return Map.of();\n    if (ext.size() > 32) {\n        throw new IllegalArgumentException(\"extensions exceeds 32 entries\");\n    }\n    return ext;\n}","typeGuard":"static boolean extensionsWithinLimit(Map<String, Object> ext) {\n    return ext == null || ext.size() <= 32;\n}","tryCatchPattern":"try {\n    AgentModelValidator.validateAgent(agent);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"extensions exceeds\")) { /* nest keys and retry */ }\n}","preventionTips":["Group flat metadata under a single nested JSON value rather than many top-level keys.","Move large blobs out of extensions into dedicated storage.","After capping, also test the serialized JSON stays under 16 KiB server-side."],"tags":["ai-agent","validation","capacity-limit","extensions","illegal-argument"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}