alibaba/nacos · error · IllegalArgumentException

invalid tag : {}

Error message

invalid tag : {}

What it means

Thrown by the v1 single-tag overload ParamUtils.checkParam(String tag) as an IllegalArgumentException (NOT a NacosApiException) when tag.trim() fails isValid(). No error code or HTTP status is attached; it is a raw runtime exception. Tags must use only letters, digits, and '_' '-' '.' ':'.

Source

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

            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "invalid dataId : " + dataId);
        }
        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,

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Sanitize the tag to the allowed charset [A-Za-z0-9_.-:] before calling the v1 API.
2. Prefer the v2 API (checkParamV2) which returns a structured NacosApiException instead of an unchecked exception.
3. Pass null/blank tag when no tag is needed.

Example fix

// before
ParamUtils.checkParam("release v1.2/tag");

// after
String tag = "release-v1-2-tag"; // whitelist-safe
ParamUtils.checkParam(tag);

private static final Pattern TAG = Pattern.compile("^[A-Za-z0-9_.\\-:]+$");
boolean validTag(String tag) {
    return tag == null || tag.isBlank() || (TAG.matcher(tag.trim()).matches() && tag.length() <= 16);
}

try {
    ParamUtils.checkParam(tag);
} catch (IllegalArgumentException e) {
    // v1 throws unchecked; convert to a user-facing validation error
    handleInvalidTag(e.getMessage());
}

When it happens

Trigger: Calling a v1 config operation that passes a tag containing spaces or special characters (e.g. 'tag with space', 'tag/1', 'tag@2'). Only reached when tag is non-blank.

Common situations: Using a human-readable label with spaces as a tag, embedding a version with '@' or '/', or copying a tag from a URL query string that includes encoded chars.

Related errors

• too long tag, over 16
• invalid tenant
• too long tenant, over 128
• 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/32e42119245e9315. Report an issue: GitHub.