alibaba/nacos · error · IllegalArgumentException

{} exceeds {} Unicode code points

Error message

{} exceeds {} Unicode code points

What it means

validateOptionalCodePointLength() enforces a Unicode code-point (not char/UTF-16) cap on optional text fields. Currently applied to displayName with MAX_DISPLAY_NAME_LENGTH (128). If the value is non-null and its code-point count exceeds the limit, it throws '<fieldName> exceeds <n> Unicode code points'.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java:244

            return;
        }
        if (value.isEmpty() || value.codePointCount(0, value.length()) > MAX_URI_LENGTH) {
            throw new IllegalArgumentException("Invalid " + fieldName);
        }
        try {
            URI uri = new URI(value);
            if (!uri.isAbsolute()) {
                throw new IllegalArgumentException(fieldName + " must be an absolute URI");
            }
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException("Invalid " + fieldName, e);
        }
    }
    
    private static void validateOptionalCodePointLength(String value, int maxLength,
        String fieldName) {
        if (value != null && value.codePointCount(0, value.length()) > maxLength) {
            throw new IllegalArgumentException(fieldName + " exceeds " + maxLength
                + " Unicode code points");
        }
    }
    
    private static void validateRequiredCodePointLength(String value, int maxLength,
        String fieldName) {
        if (value == null || value.isEmpty()
            || value.codePointCount(0, value.length()) > maxLength) {
            throw new IllegalArgumentException("Invalid " + fieldName);
        }
    }
    
    private static Map<String, Object> toStorageProjection(AgentResourceExt resourceExt) {
        Map<String, Object> result = new LinkedHashMap<String, Object>();
        result.put("schemaVersion", AgentResourceExt.SCHEMA_VERSION);
        putIfPresent(result, "displayName", resourceExt.getDisplayName());
        putIfPresent(result, "iconUrl", resourceExt.getIconUrl());
        if (resourceExt.getProvider() != null) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Shorten displayName to at most 128 code points.
2. Compute the limit the same way the validator does: value.codePointCount(0, value.length()) <= 128.
3. If you need more text, move it into extensions or a description field.

Example fix

// before
ext.setDisplayName(veryLongName); // >128 code points

// after
ext.setDisplayName(veryLongName.codePointCount(0, veryLongName.length()) <= 128
    ? veryLongName
    : veryLongName.substring(0, veryLongName.offsetByCodePoints(0, 128)));

static String clampCodePoints(String v, int max) {
    if (v == null || v.codePointCount(0, v.length()) <= max) return v;
    return v.substring(0, v.offsetByCodePoints(0, max));
}
ext.setDisplayName(clampCodePoints(ext.getDisplayName(), 128));

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

When it happens

Trigger: Setting displayName to a string longer than 128 Unicode code points (note: emoji/surrogate pairs count as one code point but two chars) via the agent create/update API.

Common situations: Long marketing/display names, names with many emoji (which inflate char count but not code-point count as much), or copy-paste of a paragraph into the display name.

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/9752a7fa4f84a44f. Report an issue: GitHub.