{"record":{"id":"a06696066638d66f","repo":"alibaba/nacos","slug":"persisted-agent-tags-must-contain-only-strings","errorCode":null,"errorMessage":"Persisted Agent tags must contain only strings","messagePattern":"Persisted Agent tags must contain only strings","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java","lineNumber":1227,"sourceCode":"    }\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        }\n        List<String> result = new ArrayList<String>(persistedTags.size());\n        for (Object persistedTag : persistedTags) {\n            if (!(persistedTag instanceof String)) {\n                throw new IllegalArgumentException(\n                    \"Persisted Agent tags must contain only strings\");\n            }\n            result.add((String) persistedTag);\n        }\n        return result;\n    }\n    \n    private String serializeVersionInfo(AgentVersionInfo versionInfo) {\n        try {\n            return JacksonUtils.toJson(toResourceVersionInfo(versionInfo));\n        } catch (NacosSerializationException e) {\n            throw new IllegalArgumentException(\"Unable to serialize Agent version info\", e);\n        }\n    }\n    \n    private ResourceVersionInfo toResourceVersionInfo(AgentVersionInfo source) {\n        if (source == null) {\n            throw new IllegalArgumentException(\"Agent versionInfo must not be null\");","sourceCodeStart":1209,"sourceCodeEnd":1245,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java#L1209-L1245","documentation":"When reading a stored Agent Resource, the persisted tags JSON array contains an element that is not a string (e.g., a number, boolean, or nested object). This guard in deserializeTags iterates every parsed element and rejects non-String instances, ensuring tags remain a List<String>.","triggerScenarios":"Any Agent read operation where the AiResource.bizTags column holds a valid JSON array but with non-string elements, e.g., [1, 2, true] instead of [\"1\", \"2\", \"true\"].","commonSituations":"Direct database manipulation wrote mixed-type JSON into bizTags. A client SDK or tool serialized tags without enforcing String types. A JSON schema mismatch between the writer and reader.","solutions":["Repair the bizTags column: ensure every array element is a JSON string, e.g., [\"tag1\", \"tag2\"].","Audit the code or tool that wrote non-string elements into the tags array.","Re-set tags through the Admin API which enforces List<String> via serializeTags."],"exampleFix":"-- SQL repair: convert to all-string array\nUPDATE ai_resource SET biz_tags = '[\"env\",\"prod\"]'\nWHERE biz_tags = '[env, 1, true]' AND type = 'agent';","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    Agent agent = persistenceService.getAgent(ns, name);\n} catch (NacosException e) {\n    if (e.getCause() instanceof IllegalArgumentException\n        && e.getMessage().contains(\"must contain only strings\")) {\n        // repair bizTags to all-string JSON array, then retry\n    }\n    throw e;\n}","preventionTips":["Always write tags through the Nacos API — serializeTags guarantees string elements.","Avoid direct column edits that bypass type enforcement.","Validate stored tag JSON after any data import."],"tags":["agent","ai-registry","data-integrity","tags","deserialization"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}