alibaba/nacos · error · IllegalArgumentException

unsupported client type: {type}

Error message

unsupported client type: {type}

What it means

Thrown by SwitchManager.update when entry is 'pushVersion' and the value's client-type segment does not match any of the five supported types: java, python, c, go, csharp. The value must be formatted as 'type:version' (split on ':'); the type part is compared case-sensitively via StringUtils.equals. Only those exact five lowercase tokens are accepted.

Source

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

                String version = parts[1];
                
                if (!version.matches(UtilsAndCommons.VERSION_STRING_SYNTAX)) {
                    throw new IllegalArgumentException(
                        "illegal version, must match: " + UtilsAndCommons.VERSION_STRING_SYNTAX);
                }
                
                if (StringUtils.equals(SwitchEntry.CLIENT_JAVA, type)) {
                    tempSwitchDomain.setPushJavaVersion(version);
                } else if (StringUtils.equals(SwitchEntry.CLIENT_PYTHON, type)) {
                    tempSwitchDomain.setPushPythonVersion(version);
                } else if (StringUtils.equals(SwitchEntry.CLIENT_C, type)) {
                    tempSwitchDomain.setPushCVersion(version);
                } else if (StringUtils.equals(SwitchEntry.CLIENT_GO, type)) {
                    tempSwitchDomain.setPushGoVersion(version);
                } else if (StringUtils.equals(SwitchEntry.CLIENT_CSHARP, type)) {
                    tempSwitchDomain.setPushCSharpVersion(version);
                } else {
                    throw new IllegalArgumentException("unsupported client type: " + type);
                }
            }
            
            if (entry.equals(SwitchEntry.PUSH_CACHE_MILLIS)) {
                long cacheMillis = Long.parseLong(value);
                
                if (cacheMillis < SwitchEntry.MIN_PUSH_CACHE_TIME_MIILIS) {
                    throw new IllegalArgumentException(
                        "min cache time for http or tcp is too small(<10000)");
                }
                
                tempSwitchDomain.setDefaultPushCacheMillis(cacheMillis);
            }
            
            // extremely careful while modifying this, cause it will affect all clients without pushing enabled
            if (entry.equals(SwitchEntry.DEFAULT_CACHE_MILLIS)) {
                long cacheMillis = Long.parseLong(value);
                

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Use one of the five supported types exactly as lowercase: java, python, c, go, csharp.
2. Ensure value format is 'type:version' with a single colon, e.g. 'java:3.0.0'.
3. Check SwitchEntry constants (java='java', python='python', c='c', go='go', csharp='csharp') for the exact token.

Example fix

// before
PUT /v3/admin/ns/operator/switches?entry=pushVersion&value=Ruby:1.0.0
// after
PUT /v3/admin/ns/operator/switches?entry=pushVersion&value=java:3.0.0

String[] SUPPORTED = {"java","python","c","go","csharp"};
String type = value.split(":")[0];
if (!Arrays.asList(SUPPORTED).contains(type)) {
    throw new IllegalArgumentException("Unsupported client type: " + type
        + ". Must be one of: " + Arrays.toString(SUPPORTED));
}

function isSupportedClientType(type: string): boolean {
  return ['java','python','c','go','csharp'].includes(type);
}

try {
  operatorV2Impl.updateSwitch("pushVersion", type + ":" + version, debug);
} catch (NacosApiException e) {
  if (e.getMessage().contains("unsupported client type")) {
    // log and prompt user with valid types
  }
  throw e;
}

When it happens

Trigger: PUT /v3/admin/ns/operator/switches with entry=pushVersion and value using an unsupported type prefix, e.g. value='ruby:1.0.0', value='node:2.0.0', value='JS:1.0.0' (case mismatch), or value='JavaScript:1.0.0'.

Common situations: Misspelling a language name, using wrong case (e.g. 'Java' instead of 'java'), using a language Nacos does not track for push-version filtering, or confusing the type:version delimiter with some other separator.

Related errors

• illegal format, must be 'type:version', but got: {value}
• illegal version, must match: {UtilsAndCommons.VERSION_STRING
• distroThreshold can not be zero or negative: {threshold}
• min cache time for http or tcp is too small(<10000)
• min default cache time is too small(<1000)

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