alibaba/nacos · warning · IllegalArgumentException

illegal format, must be 'type:version', but got: {value}

Error message

illegal format, must be 'type:version', but got: {value}

What it means

Thrown by SwitchManager.update when the 'pushVersion' switch entry value is split on ':' and produces fewer than 2 parts. The expected format is 'type:version' (e.g. 'java:1.4.2'). An IllegalArgumentException is raised. This guard ensures the push-version switch, which controls per-client-type push protocol versions, has a parseable type and version segment.

Source

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

            if (entry.equals(SwitchEntry.DISTRO_THRESHOLD)) {
                float threshold = Float.parseFloat(value);
                if (threshold <= 0) {
                    throw new IllegalArgumentException(
                        "distroThreshold can not be zero or negative: " + threshold);
                }
                tempSwitchDomain.setDistroThreshold(threshold);
            }
            
            if (entry.equals(SwitchEntry.CLIENT_BEAT_INTERVAL)) {
                long clientBeatInterval = Long.parseLong(value);
                tempSwitchDomain.setClientBeatInterval(clientBeatInterval);
            }
            
            if (entry.equals(SwitchEntry.PUSH_VERSION)) {
                
                String[] parts = value.split(":");
                if (parts.length < 2) {
                    throw new IllegalArgumentException(
                        "illegal format, must be 'type:version', but got: " + value);
                }
                String type = parts[0];
                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);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Format the value as 'type:version', e.g. 'java:1.4.2', 'python:1.0.0', 'go:1.0.0', 'c:1.0.0', 'csharp:1.0.0'.
2. Validate the input contains exactly one ':' before calling update.
3. Use one of the supported types: java, python, c, go, csharp.

Example fix

// before
switchManager.update("pushVersion", "java", false);

// after
switchManager.update("pushVersion", "java:1.4.2", false);

String value = "java:1.4.2"; // expected format
String[] parts = value.split(":");
if (parts.length < 2) {
    throw new IllegalArgumentException("pushVersion must be 'type:version'");
}
switchManager.update("pushVersion", value, false);

try {
    switchManager.update("pushVersion", value, false);
} catch (IllegalArgumentException e) {
    // malformed pushVersion — log and reject
    logger.error("Invalid pushVersion format: {}", value);
}

When it happens

Trigger: Calling the switch-update API with entry='pushVersion' and a value missing the colon separator, e.g. 'java' or '1.4.2' alone, or an empty string. The split(':') yields a single-element array, triggering the length < 2 guard.

Common situations: Operator passes only the version or only the type. Copy-paste error omitting the colon. Automation script formatting the value without the separator.

Related errors

• illegal version, must match: {UtilsAndCommons.VERSION_STRING
• distroThreshold can not be zero or negative: {threshold}
• unsupported client type: {type}
• Param 'serviceName' is illegal, it should be format as 'grou
• Param 'serviceName' is illegal, groupName can't be empty

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