{"record":{"id":"e08f02756a168978","repo":"alibaba/nacos","slug":"persisted-agent-tags-must-be-a-json-array","errorCode":null,"errorMessage":"Persisted Agent tags must be a JSON array","messagePattern":"Persisted Agent tags must be a JSON array","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java","lineNumber":1222,"sourceCode":"        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));\n        } catch (NacosSerializationException e) {\n            throw new IllegalArgumentException(\"Unable to serialize Agent version info\", e);\n        }","sourceCodeStart":1204,"sourceCodeEnd":1240,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java#L1204-L1240","documentation":"When reading a stored Agent Resource, the persisted tags JSON parsed to null instead of a List. This guard in deserializeTags checks that JacksonUtils.toObj did not return null, indicating the bizTags column holds a JSON null literal or a value that deserializes to null.","triggerScenarios":"Any Agent read operation where the AiResource.bizTags column contains the literal string 'null' (JSON null). JacksonUtils.toObj parses it successfully but returns null, which fails the non-null check at line 1221.","commonSituations":"Direct database manipulation wrote 'null' (the word) into bizTags. A serialization bug in an older version wrote JSON null instead of an empty array. A tool set the column to the string 'null' rather than '[]'.","solutions":["Repair the bizTags column: replace the literal 'null' with '[]' for affected rows.","Ensure all code paths that write bizTags use serializeTags, which always produces a valid JSON array (never null).","Audit direct database writes that bypass the Nacos API."],"exampleFix":"-- SQL repair\nUPDATE ai_resource SET biz_tags = '[]' WHERE biz_tags = 'null';\n-- or NULL\nUPDATE ai_resource SET biz_tags = '[]' WHERE biz_tags IS NULL 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 be a JSON array\")) {\n        // repair bizTags column, then retry\n    }\n    throw e;\n}","preventionTips":["Never set bizTags to 'null' or NULL — use '[]' for empty tags.","Always write tags through the API which uses serializeTags (guarantees a JSON array).","Validate bizTags data after migrations."],"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"}