alibaba/nacos · error · IllegalArgumentException

Invalid {fieldName}: exceeds {maximum}

Error message

Invalid {fieldName}: exceeds {maximum}

What it means

Thrown by validateOptionalLength when an optional string field, when present (non-null), exceeds its maximum length in code points. Unlike validateRequiredLength, null and empty are allowed; only over-length is rejected. Fields guarded: displayName (MAX_DISPLAY_NAME_LENGTH=128) and description (MAX_DESCRIPTION_LENGTH=2048).

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java:645

        try {
            URI uri = new URI(value);
            if (!uri.isAbsolute()) {
                throw new IllegalArgumentException("Invalid " + fieldName + ": " + value);
            }
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException("Invalid " + fieldName + ": " + value, e);
        }
    }
    
    private static void validateRequiredLength(String value, int maximum, String fieldName) {
        if (value == null || value.isEmpty() || codePointLength(value) > maximum) {
            throw new IllegalArgumentException("Invalid " + fieldName + ": " + value);
        }
    }
    
    private static void validateOptionalLength(String value, int maximum, String fieldName) {
        if (value != null && codePointLength(value) > maximum) {
            throw new IllegalArgumentException("Invalid " + fieldName + ": exceeds " + maximum);
        }
    }
    
    private static void validateEpochMillis(Long value, String fieldName) {
        if (value == null || value < 0) {
            throw new IllegalArgumentException(fieldName + " must be a non-negative integer");
        }
    }
    
    private static int codePointLength(String value) {
        return value.codePointCount(0, value.length());
    }
    
    private static <T> T requireNonNull(T value, String fieldName) {
        if (value == null) {
            throw new IllegalArgumentException(fieldName + " must not be null");
        }
        return value;

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Trim displayName to <= 128 code points and description to <= 2048 code points.
2. Move long-form content out of description (e.g. link to an external doc) and keep description as a short summary.
3. Enforce maxlength in the submitting UI using code-point counting, not character/byte length.
4. If you must keep a long description, host it externally and reference it from an extension.

Example fix

// before
agent.setDisplayName(veryLongMarketingTitle); // > 128 code points -> rejected
agent.setDescription(fullReadme);             // > 2048 -> rejected
// after
agent.setDisplayName(veryLongMarketingTitle.substring(0, 128));
agent.setDescription(shortSummary); // <= 2048 code points

static void optionalLen(String v, int max, String field) {
    if (v != null && v.codePointCount(0, v.length()) > max) {
        throw new IllegalArgumentException("Invalid " + field + ": exceeds " + max);
    }
}
optionalLen(agent.getDisplayName(), 128, "displayName");
optionalLen(agent.getDescription(), 2048, "description");

static boolean optionalLengthOk(String v, int max) {
    return v == null || v.codePointCount(0, v.length()) <= max;
}

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("exceeds 128") || e.getMessage().contains("exceeds 2048")) {
        // trim displayName/description and retry
    } else throw e;
}

When it happens

Trigger: Agent publish/update via validateAgentFields with a displayName longer than 128 code points, or a description longer than 2048 code points. Null/empty values for these two are accepted.

Common situations: Pasting a long marketing display name; a description field populated from a README or multi-paragraph doc; emoji/CJK content where code points exceed the cap well before byte length would; UI not enforcing a maxlength on these inputs.

Related errors

• Invalid Agent Version storage {field}
• Invalid {fieldName}: {value}
• Invalid agentName: {agentName}
• 20002
• 10000

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