alibaba/nacos · warning · IllegalArgumentException

illegal version, must match: {UtilsAndCommons.VERSION_STRING

Error message

illegal version, must match: {UtilsAndCommons.VERSION_STRING_SYNTAX}

What it means

Thrown by SwitchManager.update when the 'pushVersion' value's version segment (after splitting on ':') does not match the regex UtilsAndCommons.VERSION_STRING_SYNTAX, which is '[0-9]+\.[0-9]+\.[0-9]+' — exactly three dot-separated numeric groups (e.g. '1.4.2'). An IllegalArgumentException is raised. This ensures push-version strings are semver-like and parseable by client SDKs.

Source

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

            }
            
            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);
                } else if (StringUtils.equals(SwitchEntry.CLIENT_CSHARP, type)) {
                    tempSwitchDomain.setPushCSharpVersion(version);
                } else {
                    throw new IllegalArgumentException("unsupported client type: " + type);
                }
            }

View on GitHub (pinned to 9b989acdf1)

Solutions

Provide a version matching exactly X.Y.Z where X, Y, Z are non-negative integers, e.g. '1.4.2'.
Strip any 'v' prefix, build metadata, or pre-release suffix before passing the value.
Validate with the regex '[0-9]+\.[0-9]+\.[0-9]+' client-side before calling update.

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

String version = "1.4.2"; // version segment only
if (!version.matches("[0-9]+\\.[0-9]+\\.[0-9]+")) {
    throw new IllegalArgumentException("Version must be X.Y.Z");
}
switchManager.update("pushVersion", "java:" + version, false);

Try / catch

try {
    switchManager.update("pushVersion", value, false);
} catch (IllegalArgumentException e) {
    // version did not match regex — log and reject
    logger.error("Invalid pushVersion segment: {}", value);
}

Prevention

Provide versions in strict X.Y.Z format (three numeric groups).
Strip 'v' prefixes, build metadata, and pre-release suffixes.
Validate with the regex '[0-9]+\\.[0-9]+\\.[0-9]+' before calling update.

When it happens

Trigger: Calling the switch-update API with entry='pushVersion' and a version segment like '1.4' (two groups), '1.4.2.0' (four groups), 'v1.4.2' (leading non-numeric), or '1.4.x' (non-numeric group). The regex match fails.

Common situations: Operator passes a two-part version ('1.4') or includes a 'v' prefix or pre-release suffix ('1.4.2-SNAPSHOT'). Version copied from a build tool that uses a different format. CI pipeline injecting a git hash or timestamp instead of a semver.

Related errors

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