{"record":{"id":"47fa2c3db8937d0d","repo":"alibaba/nacos","slug":"invalid-persisted-agent-tags","errorCode":null,"errorMessage":"Invalid persisted Agent tags","messagePattern":"Invalid persisted Agent tags","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java","lineNumber":1219,"sourceCode":"        } 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        }\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));","sourceCodeStart":1201,"sourceCodeEnd":1237,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java#L1201-L1237","documentation":"When reading a stored Agent Resource, the persisted tags JSON failed to deserialize into a List. This guard in deserializeTags wraps JacksonUtils.toObj and catches NacosDeserializationException, indicating the stored bizTags column contains malformed JSON that is not a valid JSON array.","triggerScenarios":"Any Agent read operation (GET /v3/admin/ai/agent, list, or summary) where the AiResource.bizTags column holds a value that JacksonUtils.toObj(json, List.class) cannot parse. Called from toAgent (line 1318), toAgentSummary (line 1341), and the equivalence check at line 1460.","commonSituations":"Direct database manipulation wrote a non-JSON value into the bizTags column. A bug in an older server version wrote corrupt tag data. A storage migration or backup restore introduced encoding issues.","solutions":["Inspect the AiResource.bizTags column for the affected Agent and repair the malformed JSON or set it to a valid JSON array string.","If the value is empty or blank, the server already handles it (returns empty list); ensure it is not partial JSON like '['.","Run a data-integrity check across all Agent Resource rows to find and fix other corrupt tag values."],"exampleFix":"// SQL repair — set corrupt tags to a valid empty JSON array\n// UPDATE ai_resource SET biz_tags = '[]' WHERE biz_tags IS NOT NULL AND biz_tags NOT LIKE '[%';\n// Or clear and re-set via the Admin API after fixing the column.","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(\"Invalid persisted Agent tags\")) {\n        // repair stored bizTags, then retry\n    }\n    throw e;\n}","preventionTips":["Never write directly to the bizTags column; always use the Admin API.","Run data validation after storage migrations or backup restores.","Monitor deserialization errors as a data-integrity signal."],"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"}