What causes "illegal normal status code: {statusCode}" in alibaba/nacos?

Use a valid positive HTTP status code (1-999), typically 200, 403, 429, or 503.

alibaba/nacos · error · IllegalArgumentException

illegal normal status code: {statusCode}

Error message

illegal normal status code: {statusCode}

What it means

Thrown when entry is 'limitedUrlMap' and the status code parsed from the part after ':' is <= 0. Status codes must be positive integers (e.g. 200, 403, 503).

Source

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

                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);
                        
                    }
                    
                    tempSwitchDomain.setLimitedUrlMap(limitedUrlMap);
                }
            }
            
            if (entry.equals(SwitchEntry.ENABLE_STANDALONE)) {
                
                if (StringUtils.isNotEmpty(value)) {
                    tempSwitchDomain.setEnableStandalone(Boolean.parseBoolean(value));
                }
            }

View on GitHub (pinned to 9b989acdf1)

Solutions

Use a valid positive HTTP status code (1-999), typically 200, 403, 429, or 503.
Ensure the segment after ':' is a parseable positive integer.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

for (String entry : value.split(",")) {
    String[] parts = entry.split(":", 2);
    int code = Integer.parseInt(parts[1]);
    if (code <= 0) {
        throw new IllegalArgumentException("Status code must be positive: " + code);
    }
}

Type guard

function hasValidStatusCodes(value: string): boolean {
  return value.split(',').every(e => {
    const parts = e.split(':');
    const code = parseInt(parts[1], 10);
    return !isNaN(code) && code > 0;
  });
}

Try / catch

try {
  operatorV2Impl.updateSwitch("limitedUrlMap", value, debug);
} catch (NacosApiException e) {
  if (e.getMessage().contains("illegal normal status code")) {
    // fix status codes to valid positive values
  }
}

Prevention

Use standard HTTP status codes (200, 403, 429, 503).
Never use 0 or negative values.

When it happens

Trigger: PUT /v3/admin/ns/operator/switches with entry=limitedUrlMap and value with non-positive status code, e.g. value='/nacos:0', value='/nacos:-1', or non-integer value='/nacos:abc' (which throws NumberFormatException before this check).

Common situations: Using 0 to mean 'disabled', passing negative codes, or typos in the numeric portion.

Related errors

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