alibaba/nacos · error · IllegalArgumentException

too long tag, over 16

Error message

too long tag, over 16

What it means

Thrown by the v1 single-tag overload ParamUtils.checkParam(String tag) as an IllegalArgumentException when tag.length() exceeds TAG_MAX_LEN (16). It is an unchecked runtime exception with no error code/HTTP status. Enforces short, machine-friendly tags for indexing and push filtering.

Source

Thrown at config/src/main/java/com/alibaba/nacos/config/server/utils/ParamUtils.java:140

        }
        if (StringUtils.isBlank(group) || !isValid(group)) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "invalid group : " + group);
        }
        checkTenantV2(namespaceId);
    }
    
    /**
     * Check the tag for [v1].
     */
    public static void checkParam(String tag) {
        if (StringUtils.isNotBlank(tag)) {
            if (!isValid(tag.trim())) {
                throw new IllegalArgumentException("invalid tag : " + tag);
            }
            if (tag.length() > TAG_MAX_LEN) {
                throw new IllegalArgumentException("too long tag, over 16");
            }
        }
    }
    
    /**
     * Check the config info for [v1] and [v2].
     */
    public static void checkParam(Map<String, Object> configAdvanceInfo) throws NacosException {
        for (Map.Entry<String, Object> configAdvanceInfoTmp : configAdvanceInfo.entrySet()) {
            if (CONFIG_TAGS.equals(configAdvanceInfoTmp.getKey())) {
                if (configAdvanceInfoTmp.getValue() != null) {
                    String[] tagArr = ((String) configAdvanceInfoTmp.getValue()).split(",");
                    if (tagArr.length > 5) {
                        throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                            ErrorCode.PARAMETER_VALIDATE_ERROR,
                            "too much config_tags, over 5");
                    }
                    for (String tag : tagArr) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Shorten the tag to at most 16 characters.
2. Move long descriptive metadata into the 'desc' advance-info field (max 128) instead of the tag.
3. Use a compact encoding (e.g. abbreviated codes) for composite tag values.

Example fix

// before
ParamUtils.checkParam("production-blue-cluster"); // 24 chars

// after
ParamUtils.checkParam("prod-blue"); // 9 chars, fits TAG_MAX_LEN=16

boolean validTagLength(String tag) {
    return tag == null || tag.length() <= 16;
}

try {
    ParamUtils.checkParam(tag);
} catch (IllegalArgumentException e) {
    handleInvalidTag(e.getMessage());
}

When it happens

Trigger: A v1 config operation passing a tag whose length is greater than 16 characters (after the charset check passes).

Common situations: Using a descriptive sentence or UUID as a tag, concatenating env+version+region into one tag field.

Related errors

• invalid tag : {}
• too long tenant, over 128
• invalid tenant
• Plugin config value cannot be null: {key}
• Plugin config value must be positive: {key}

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