{"record":{"id":"b55c3fee3f2c0ac2","repo":"alibaba/nacos","slug":"unable-to-serialize-agent-extensions","errorCode":null,"errorMessage":"Unable to serialize Agent extensions","messagePattern":"Unable to serialize Agent extensions","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java","lineNumber":163,"sourceCode":"        }\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) {\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;","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java#L145-L181","documentation":"validateExtensions() re-serializes the extensions map with JacksonUtils.toJsonBytes to measure its on-wire size; if that serialization throws NacosSerializationException the ext is rejected as 'Unable to serialize Agent extensions'. This indicates a value inside the map that Jackson cannot serialize at all (e.g. a non-JSON Java object) — distinct from the per-value type guard which catches most cases first.","triggerScenarios":"An extensions value is a Java object Jackson has no serializer for (a raw POJO without recognized shape, a self-referential structure, or a type with no default serialization), so the byte-size measurement step fails.","commonSituations":"Putting a domain object, a Date, a Joda/Java-time type, or a circular reference into extensions instead of a plain JSON-compatible value.","solutions":["Store only JSON-primitive compatible values (String, Boolean, Number, List, Map) in extensions; convert complex objects to Map/List first.","Register/enable the needed Jackson modules only if you intentionally serialize richer types — but prefer plain structures.","Reproduce locally with JacksonUtils.toJsonBytes(ext) to find the failing value."],"exampleFix":"// before\next.put(\"createdAt\", Instant.now()); // Jackson fails without JavaTimeModule wiring\n\n// after\next.put(\"createdAt\", Instant.now().toString()); // ISO-8601 string","handlingStrategy":"validation","validationCode":"try {\n    com.alibaba.nacos.common.utils.JacksonUtils.toJsonBytes(extensions);\n} catch (NacosSerializationException e) {\n    throw new AgentExtUnserializableException(e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    AgentResourceExtSerializer.serialize(resourceExt);\n} catch (IllegalArgumentException e) {\n    if (\"Unable to serialize Agent extensions\".equals(e.getMessage())) {\n        // a value in extensions is not JSON-serializable; replace complex objects with Map/String\n        sanitizeExtensions(extensions);\n    } else throw e;\n}","preventionTips":["Store only JSON-primitive-compatible values (String, Boolean, Number, List, Map) in extensions.","Convert Date/Instant/UUID/enum to strings before insertion.","Avoid circular references and unregistered POJOs."],"tags":["ai-registry","agent","extensions","serialization"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}