{"record":{"id":"5f2442e0ee64e354","repo":"alibaba/nacos","slug":"agent-extensions-exceeds-bytes","errorCode":null,"errorMessage":"Agent extensions exceeds {} bytes","messagePattern":"Agent extensions exceeds (.+?) bytes","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java","lineNumber":166,"sourceCode":"                \"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) {\n            throw new IllegalArgumentException(\n                \"Agent extensions exceeds \" + MAX_EXTENSIONS_SIZE + \" bytes\");\n        }\n    }\n    \n    private static void validateJsonValue(Object value, String fieldName) {\n        if (value == null || value instanceof String || value instanceof Boolean\n            || value instanceof Byte || value instanceof Short || value instanceof Integer\n            || value instanceof Long) {\n            return;\n        }\n        if (value instanceof Float) {\n            if (!Float.isFinite((Float) value)) {\n                throw new IllegalArgumentException(fieldName + \" must be a finite JSON number\");\n            }\n            return;\n        }\n        if (value instanceof Double) {\n            if (!Double.isFinite((Double) value)) {","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java#L148-L184","documentation":"After successful re-serialization, validateExtensions() enforces MAX_EXTENSIONS_SIZE (16384 bytes / 16 KiB) on the UTF-8 byte length of the extensions map. This is the hard storage budget for the free-form extension bag, independent of the 32-entry count cap.","triggerScenarios":"An agent create/update whose extensions serialize to more than 16384 bytes (e.g. large embedded base64 blobs, big nested structures, or many moderately-sized values).","commonSituations":"Embedding an icon/logo as base64 in extensions, pasting large config documents, or accumulating verbose metadata.","solutions":["Trim the extensions payload below 16 KiB; store large blobs out-of-band (e.g. an object store URL) and keep only a reference in extensions.","Compress or shorten verbose keys/values.","Measure with JacksonUtils.toJsonBytes(extensions).length before publishing."],"exampleFix":"// before\next.put(\"badge\", base64ImageOf14Kb); // pushes total over 16384\n\n// after\next.put(\"badgeUrl\", \"https://cdn.example.com/agent.png\");","handlingStrategy":"validation","validationCode":"int size = com.alibaba.nacos.common.utils.JacksonUtils.toJsonBytes(extensions).length;\nif (size > AgentResourceExtSerializer.MAX_EXTENSIONS_SIZE) {\n    throw new AgentExtTooLargeException(size, AgentResourceExtSerializer.MAX_EXTENSIONS_SIZE);\n}","typeGuard":null,"tryCatchPattern":"try {\n    AgentResourceExtSerializer.serialize(resourceExt);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Agent extensions exceeds\")) {\n        // move large blobs to external storage and keep only a URL reference\n        externalizeLargeExtensions(extensions);\n    } else throw e;\n}","preventionTips":["Measure the serialized byte length before publishing.","Keep extensions metadata-only; store blobs externally.","Shorten verbose keys and values."],"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"}