alibaba/nacos · critical · IllegalArgumentException

Persisted Agent tags must contain only strings

Error message

Persisted Agent tags must contain only strings

What it means

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

Source

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

    }
    
    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);
        }
    }
    
    private ResourceVersionInfo toResourceVersionInfo(AgentVersionInfo source) {
        if (source == null) {
            throw new IllegalArgumentException("Agent versionInfo must not be null");

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Repair the bizTags column: ensure every array element is a JSON string, e.g., ["tag1", "tag2"].
  2. Audit the code or tool that wrote non-string elements into the tags array.
  3. Re-set tags through the Admin API which enforces List<String> via serializeTags.

Example fix

-- SQL repair: convert to all-string array
UPDATE ai_resource SET biz_tags = '["env","prod"]'
WHERE biz_tags = '[env, 1, true]' 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 contain only strings")) {
        // repair bizTags to all-string JSON array, then retry
    }
    throw e;
}

Prevention

When it happens

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

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

Related errors

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