alibaba/nacos · error · IllegalArgumentException

invalid tenant

Error message

invalid tenant

What it means

Thrown by the v1 ParamUtils.checkTenant(String tenant) as an IllegalArgumentException (unchecked, no error code/HTTP status) when tenant.trim() fails isValid(): only letters, digits, and '_' '-' '.' ':' are allowed. 'tenant' is the legacy name for namespaceId and is used as a storage partition key.

Source

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

                throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                    ErrorCode.PARAMETER_VALIDATE_ERROR,
                    "invalid tag : " + tag);
            }
            if (tag.length() > TAG_MAX_LEN) {
                throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                    ErrorCode.PARAMETER_VALIDATE_ERROR,
                    "too long tag, over 16");
            }
        }
    }
    
    /**
     * Check the tenant for [v1].
     */
    public static void checkTenant(String tenant) {
        if (StringUtils.isNotBlank(tenant)) {
            if (!isValid(tenant.trim())) {
                throw new IllegalArgumentException("invalid tenant");
            }
            if (tenant.length() > TENANT_MAX_LEN) {
                throw new IllegalArgumentException("too long tenant, over 128");
            }
        }
    }
    
    /**
     * Check the namespaceId for [v2].
     */
    public static void checkTenantV2(String namespaceId) throws NacosApiException {
        if (StringUtils.isNotBlank(namespaceId)) {
            if (!isValid(namespaceId.trim())) {
                throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                    ErrorCode.PARAMETER_VALIDATE_ERROR,
                    "invalid namespaceId");
            }
            if (namespaceId.length() > TENANT_MAX_LEN) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Sanitize the tenant to the allowed charset [A-Za-z0-9_.-:].
2. Prefer the v2 API (checkTenantV2) for a structured NacosApiException.
3. Use the namespace's generated id rather than its display name as the tenant value.

Example fix

// before
ParamUtils.checkTenant("prod environment");

// after
ParamUtils.checkTenant("prod-env"); // whitelist-safe

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

try {
    ParamUtils.checkTenant(tenant);
} catch (IllegalArgumentException e) {
    handleInvalidTenant(e.getMessage());
}

When it happens

Trigger: A v1 config operation passing a non-blank tenant containing spaces or special characters (e.g. 'prod env', 'tenant/1').

Common situations: Using a descriptive namespace name with spaces as tenant, embedding slashes, or copying a tenant id from a URL with encoded characters.

Related errors

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