What causes "Invalid persisted Agent tags" in alibaba/nacos?

Inspect the AiResource.bizTags column for the affected Agent and repair the malformed JSON or set it to a valid JSON array string.

alibaba/nacos · critical · IllegalArgumentException

Invalid persisted Agent tags

Error message

Invalid persisted Agent tags

What it means

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.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java:1219

        } catch (NacosSerializationException e) {
            throw new IllegalArgumentException("Unable to serialize Agent tags", e);
        }
        if (result.length() > MAX_BIZ_TAGS_LENGTH) {
            throw new IllegalArgumentException(
                "Agent tags exceeds " + MAX_BIZ_TAGS_LENGTH + " persisted characters");
        }
        return result;
    }
    
    private List<String> deserializeTags(String json) {
        if (json == null || json.trim().isEmpty()) {
            return Collections.emptyList();
        }
        final List<?> persistedTags;
        try {
            persistedTags = JacksonUtils.toObj(json, List.class);
        } catch (NacosDeserializationException e) {
            throw new IllegalArgumentException("Invalid persisted Agent tags", e);
        }
        if (persistedTags == null) {
            throw new IllegalArgumentException("Persisted Agent tags must be a JSON array");
        }
        List<String> result = new ArrayList<String>(persistedTags.size());
        for (Object persistedTag : persistedTags) {
            if (!(persistedTag instanceof String)) {
                throw new IllegalArgumentException(
                    "Persisted Agent tags must contain only strings");
            }
            result.add((String) persistedTag);
        }
        return result;
    }
    
    private String serializeVersionInfo(AgentVersionInfo versionInfo) {
        try {
            return JacksonUtils.toJson(toResourceVersionInfo(versionInfo));

View on GitHub (pinned to 9b989acdf1)

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.

Example fix

// SQL repair — set corrupt tags to a valid empty JSON array
// UPDATE ai_resource SET biz_tags = '[]' WHERE biz_tags IS NOT NULL AND biz_tags NOT LIKE '[%';
// Or clear and re-set via the Admin API after fixing the column.

Defensive patterns

Strategy: try-catch

Try / catch

try {
    Agent agent = persistenceService.getAgent(ns, name);
} catch (NacosException e) {
    if (e.getCause() instanceof IllegalArgumentException
        && e.getMessage().contains("Invalid persisted Agent tags")) {
        // repair stored bizTags, then retry
    }
    throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/47fa2c3db8937d0d. Report an issue: GitHub.