alibaba/nacos · critical · IllegalArgumentException

Persisted Agent tags must be a JSON array

Error message

Persisted Agent tags must be a JSON array

What it means

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.

Source

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

        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));
        } catch (NacosSerializationException e) {
            throw new IllegalArgumentException("Unable to serialize Agent version info", e);
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Repair the bizTags column: replace the literal 'null' with '[]' for affected rows.
  2. Ensure all code paths that write bizTags use serializeTags, which always produces a valid JSON array (never null).
  3. Audit direct database writes that bypass the Nacos API.

Example fix

-- SQL repair
UPDATE ai_resource SET biz_tags = '[]' WHERE biz_tags = 'null';
-- or NULL
UPDATE ai_resource SET biz_tags = '[]' WHERE biz_tags IS NULL AND type = 'agent';
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("must be a JSON array")) {
        // repair bizTags column, then retry
    }
    throw e;
}

Prevention

When it happens

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

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

Related errors

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