{"record":{"id":"0d501673d881beff","repo":"alibaba/nacos","slug":"agent-tags-exceeds-s-persisted-characters","errorCode":null,"errorMessage":"Agent tags exceeds %s persisted characters","messagePattern":"Agent tags exceeds (.+?) persisted characters","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java","lineNumber":1205,"sourceCode":"        }\n        List<String> result = new ArrayList<String>(callInterfaces.size());\n        for (AgentCallInterface callInterface : callInterfaces) {\n            result.add(callInterface.getProtocol());\n        }\n        return result;\n    }\n    \n    private String serializeTags(List<String> tags) {\n        List<String> persistedTags =\n            tags == null ? Collections.<String>emptyList() : tags;\n        final String result;\n        try {\n            result = JacksonUtils.toJson(persistedTags);\n        } catch (NacosSerializationException e) {\n            throw new IllegalArgumentException(\"Unable to serialize Agent tags\", e);\n        }\n        if (result.length() > MAX_BIZ_TAGS_LENGTH) {\n            throw new IllegalArgumentException(\n                \"Agent tags exceeds \" + MAX_BIZ_TAGS_LENGTH + \" persisted characters\");\n        }\n        return result;\n    }\n    \n    private List<String> deserializeTags(String json) {\n        if (json == null || json.trim().isEmpty()) {\n            return Collections.emptyList();\n        }\n        final List<?> persistedTags;\n        try {\n            persistedTags = JacksonUtils.toObj(json, List.class);\n        } catch (NacosDeserializationException e) {\n            throw new IllegalArgumentException(\"Invalid persisted Agent tags\", e);\n        }\n        if (persistedTags == null) {\n            throw new IllegalArgumentException(\"Persisted Agent tags must be a JSON array\");\n        }","sourceCodeStart":1187,"sourceCodeEnd":1223,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java#L1187-L1223","documentation":"Agent tags are serialized to a JSON string for persistence, and the resulting string must not exceed 1024 characters (MAX_BIZ_TAGS_LENGTH). This guard in serializeTags runs during toResourceRow when creating or updating an Agent Resource, preventing oversized tag payloads from degrading storage and query performance.","triggerScenarios":"Creating or updating an Agent (POST/PUT) with a tags list whose JSON serialization exceeds 1024 characters. The serializeTags method at line 1195 calls JacksonUtils.toJson and checks the result length against MAX_BIZ_TAGS_LENGTH (1024) before storing.","commonSituations":"A client submits many tags or very long tag strings. A migration imports verbose tag metadata. Automated tooling generates descriptive tags that grow unbounded.","solutions":["Reduce the number of tags or shorten individual tag strings so the JSON array stays under 1024 characters.","Move large metadata to the extensions map instead of tags.","Pre-check the serialized length: JacksonUtils.toJson(tags).length() <= 1024 before submitting."],"exampleFix":"// before\nagent.setTags(List.of(\n    \"very-long-tag-value-1-that-takes-up-space\",\n    \"very-long-tag-value-2-that-takes-up-space\",\n    /* ... many more ... */\n)); // JSON exceeds 1024 chars\n\n// after\nagent.setTags(List.of(\"env:prod\", \"team:platform\"));\n// or move large data to extensions\nagent.setExtensions(Map.of(\"metadata\", largeMetadata));","handlingStrategy":"validation","validationCode":"String json = JacksonUtils.toJson(agent.getTags() != null ? agent.getTags() : Collections.emptyList());\nif (json.length() > 1024) {\n    throw new IllegalArgumentException(\"Agent tags JSON exceeds 1024 chars: \" + json.length());\n}","typeGuard":"boolean tagsWithinLimit(List<String> tags) {\n    if (tags == null) return true;\n    try {\n        return JacksonUtils.toJson(tags).length() <= 1024;\n    } catch (Exception e) { return false; }\n}","tryCatchPattern":null,"preventionTips":["Keep tags short and few — treat the 1024-char JSON limit as a hard ceiling.","Use the extensions map for verbose metadata, not tags.","Validate serialized tag length client-side before submission."],"tags":["agent","ai-registry","validation","tags","size-limit"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}