alibaba/nacos · error · IllegalArgumentException

Agent tags exceeds %s persisted characters

Error message

Agent tags exceeds %s persisted characters

What it means

Agent tags are serialized to a JSON string for persistence, and the resulting string must not exceed 1024 characters (MAX_BIZ_TAGS_LENGTH). This guard in serializeTags runs during toResourceRow when creating or updating an Agent Resource, preventing oversized tag payloads from degrading storage and query performance.

Source

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

        }
        List<String> result = new ArrayList<String>(callInterfaces.size());
        for (AgentCallInterface callInterface : callInterfaces) {
            result.add(callInterface.getProtocol());
        }
        return result;
    }
    
    private String serializeTags(List<String> tags) {
        List<String> persistedTags =
            tags == null ? Collections.<String>emptyList() : tags;
        final String result;
        try {
            result = JacksonUtils.toJson(persistedTags);
        } 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");
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Reduce the number of tags or shorten individual tag strings so the JSON array stays under 1024 characters.
2. Move large metadata to the extensions map instead of tags.
3. Pre-check the serialized length: JacksonUtils.toJson(tags).length() <= 1024 before submitting.

Example fix

// before
agent.setTags(List.of(
    "very-long-tag-value-1-that-takes-up-space",
    "very-long-tag-value-2-that-takes-up-space",
    /* ... many more ... */
)); // JSON exceeds 1024 chars

// after
agent.setTags(List.of("env:prod", "team:platform"));
// or move large data to extensions
agent.setExtensions(Map.of("metadata", largeMetadata));

String json = JacksonUtils.toJson(agent.getTags() != null ? agent.getTags() : Collections.emptyList());
if (json.length() > 1024) {
    throw new IllegalArgumentException("Agent tags JSON exceeds 1024 chars: " + json.length());
}

boolean tagsWithinLimit(List<String> tags) {
    if (tags == null) return true;
    try {
        return JacksonUtils.toJson(tags).length() <= 1024;
    } catch (Exception e) { return false; }
}

When it happens

Trigger: Creating or updating an Agent (POST/PUT) with a tags list whose JSON serialization exceeds 1024 characters. The serializeTags method at line 1195 calls JacksonUtils.toJson and checks the result length against MAX_BIZ_TAGS_LENGTH (1024) before storing.

Common situations: A client submits many tags or very long tag strings. A migration imports verbose tag metadata. Automated tooling generates descriptive tags that grow unbounded.

Related errors

• Online Agent Version must contain callInterfaces
• Agent Version namespaceId does not match request
• Agent Version agentName does not match request
• Agent Version status must be online
• Agent Version must not contain read-only projection fields

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