alibaba/nacos · error · IllegalArgumentException

invalid input for limited urls

Error message

invalid input for limited urls

What it means

Thrown when entry is 'limitedUrlMap' and a comma-separated entry lacks the ':' separator, so parts.length < 2. Each limited-URL entry must be 'url:statusCode'. This map configures URLs that return a specific status code (rate-limiting / circuit-breaking).

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/misc/SwitchManager.java:251

                
                tempSwitchDomain.setDisableAddIP(disableAddIp);
            }
            
            if (entry.equals(SwitchEntry.SEND_BEAT_ONLY)) {
                boolean sendBeatOnly = Boolean.parseBoolean(value);
                
                tempSwitchDomain.setSendBeatOnly(sendBeatOnly);
            }
            
            if (entry.equals(SwitchEntry.LIMITED_URL_MAP)) {
                Map<String, Integer> limitedUrlMap = new HashMap<>(16);
                
                if (!StringUtils.isEmpty(value)) {
                    String[] entries = value.split(",");
                    for (String each : entries) {
                        String[] parts = each.split(":");
                        if (parts.length < 2) {
                            throw new IllegalArgumentException("invalid input for limited urls");
                        }
                        
                        String limitedUrl = parts[0];
                        if (StringUtils.isEmpty(limitedUrl)) {
                            throw new IllegalArgumentException(
                                "url can not be empty, url: " + limitedUrl);
                        }
                        
                        int statusCode = Integer.parseInt(parts[1]);
                        if (statusCode <= 0) {
                            throw new IllegalArgumentException(
                                "illegal normal status code: " + statusCode);
                        }
                        
                        limitedUrlMap.put(limitedUrl, statusCode);
                        
                    }
                    

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Format each entry as 'url:statusCode', comma-separated, e.g. '/nacos:403,/health:200'.
2. Ensure every entry has exactly one colon separating URL and status code.

Example fix

// before
PUT /v3/admin/ns/operator/switches?entry=limitedUrlMap&value=/nacos
// after
PUT /v3/admin/ns/operator/switches?entry=limitedUrlMap&value=/nacos:403

for (String entry : value.split(",")) {
    String[] parts = entry.split(":");
    if (parts.length < 2) {
        throw new IllegalArgumentException("Each limitedUrl entry must be 'url:statusCode'");
    }
}

function isValidLimitedUrlMap(value: string): boolean {
  return value.split(',').every(e => {
    const parts = e.split(':');
    return parts.length >= 2 && parts[0].length > 0;
  });
}

try {
  operatorV2Impl.updateSwitch("limitedUrlMap", value, debug);
} catch (NacosApiException e) {
  if (e.getMessage().contains("invalid input")) {
    // re-format value with proper url:code pairs
  }
}

When it happens

Trigger: PUT /v3/admin/ns/operator/switches with entry=limitedUrlMap and value containing an entry without a colon, e.g. value='/nacos' or value='/nacos:403,/health' (second entry missing colon).

Common situations: Forgetting the ':statusCode' suffix on one or more entries, or using a different delimiter.

Related errors

• url can not be empty, url: {limitedUrl}
• illegal normal status code: {statusCode}
• distroThreshold can not be zero or negative: {threshold}
• illegal format, must be 'type:version', but got: {value}
• illegal version, must match: {UtilsAndCommons.VERSION_STRING

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