{"record":{"id":"734d5e323185d58c","repo":"alibaba/nacos","slug":"extensions-exceeds-32-entries","errorCode":null,"errorMessage":"extensions exceeds 32 entries","messagePattern":"extensions exceeds 32 entries","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java","lineNumber":147,"sourceCode":"        validateExtensions(resourceExt.getExtensions());\n        validateCatalog(resourceExt.getVersionCatalog());\n    }\n    \n    private static void validateProvider(AgentProvider provider) {\n        if (provider == null) {\n            return;\n        }\n        validateRequiredCodePointLength(provider.getName(), MAX_PROVIDER_NAME_LENGTH,\n            \"provider.name\");\n        validateOptionalAbsoluteUri(provider.getUrl(), \"provider.url\");\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 (Map.Entry<?, ?> entry : extensions.entrySet()) {\n            if (!(entry.getKey() instanceof String)) {\n                throw new IllegalArgumentException(\n                    \"Agent extensions contains a non-string JSON object key\");\n            }\n            String key = (String) entry.getKey();\n            validateRequiredCodePointLength(key, MAX_EXTENSION_KEY_LENGTH, \"extension key\");\n            validateJsonValue(entry.getValue(), \"extension \" + entry.getKey());\n        }\n        final byte[] bytes;\n        try {\n            bytes = JacksonUtils.toJsonBytes(extensions);\n        } catch (NacosSerializationException e) {\n            throw new IllegalArgumentException(\"Unable to serialize Agent extensions\", e);\n        }\n        if (bytes.length > MAX_EXTENSIONS_SIZE) {","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java#L129-L165","documentation":"validateExtensions() caps the extensions map at MAX_EXTENSIONS (32) entries. The cap bounds storage and validation cost for the free-form extension bag. Once the entry count exceeds 32 the whole ext is rejected before any per-entry work.","triggerScenarios":"An agent create/update supplies an extensions map with more than 32 keys via the AI admin API; AgentPersistenceService.serialize propagates the failure on persist.","commonSituations":"A client dumping many ad-hoc metadata keys (telemetry tags, feature flags) into extensions instead of using dedicated model fields, or a loop that auto-generates extension keys.","solutions":["Reduce the extensions map to at most 32 keys; move redundant keys into a single nested JSON object under one extension key if you need grouping.","Prefer first-class AgentResourceExt fields (provider, versionCatalog) over extensions for data the model already represents.","Add a client-side size assertion before publishing the agent."],"exampleFix":"// before\nMap<String, Object> ext = new HashMap<>();\nfor (int i = 0; i < 50; i++) ext.put(\"k\" + i, i); // >32 entries\nresourceExt.setExtensions(ext);\n\n// after\nMap<String, Object> ext = new HashMap<>();\nfor (int i = 0; i < 32; i++) ext.put(\"k\" + i, i); // keep <= 32","handlingStrategy":"validation","validationCode":"if (extensions != null && extensions.size() > 32) {\n    throw new AgentExtTooManyEntriesException(extensions.size(), 32);\n}","typeGuard":null,"tryCatchPattern":"try {\n    AgentResourceExtSerializer.serialize(resourceExt);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"extensions exceeds\")) {\n        // trim or move keys into a single nested object, then retry\n        trimExtensions(extensions);\n    } else throw e;\n}","preventionTips":["Assert extensions.size() <= 32 before publishing.","Prefer model fields over extensions for data the schema already represents.","Group related ad-hoc keys under one extension key when the count grows."],"tags":["ai-registry","agent","extensions","size-limit"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}