{"record":{"id":"19425e47795eb893","repo":"alibaba/nacos","slug":"illegal-version-must-match-utilsandcommons-vers","errorCode":null,"errorMessage":"illegal version, must match: {UtilsAndCommons.VERSION_STRING_SYNTAX}","messagePattern":"illegal version, must match: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"warning","filePath":"naming/src/main/java/com/alibaba/nacos/naming/misc/SwitchManager.java","lineNumber":141,"sourceCode":"            }\n            \n            if (entry.equals(SwitchEntry.CLIENT_BEAT_INTERVAL)) {\n                long clientBeatInterval = Long.parseLong(value);\n                tempSwitchDomain.setClientBeatInterval(clientBeatInterval);\n            }\n            \n            if (entry.equals(SwitchEntry.PUSH_VERSION)) {\n                \n                String[] parts = value.split(\":\");\n                if (parts.length < 2) {\n                    throw new IllegalArgumentException(\n                        \"illegal format, must be 'type:version', but got: \" + value);\n                }\n                String type = parts[0];\n                String version = parts[1];\n                \n                if (!version.matches(UtilsAndCommons.VERSION_STRING_SYNTAX)) {\n                    throw new IllegalArgumentException(\n                        \"illegal version, must match: \" + UtilsAndCommons.VERSION_STRING_SYNTAX);\n                }\n                \n                if (StringUtils.equals(SwitchEntry.CLIENT_JAVA, type)) {\n                    tempSwitchDomain.setPushJavaVersion(version);\n                } else if (StringUtils.equals(SwitchEntry.CLIENT_PYTHON, type)) {\n                    tempSwitchDomain.setPushPythonVersion(version);\n                } else if (StringUtils.equals(SwitchEntry.CLIENT_C, type)) {\n                    tempSwitchDomain.setPushCVersion(version);\n                } else if (StringUtils.equals(SwitchEntry.CLIENT_GO, type)) {\n                    tempSwitchDomain.setPushGoVersion(version);\n                } else if (StringUtils.equals(SwitchEntry.CLIENT_CSHARP, type)) {\n                    tempSwitchDomain.setPushCSharpVersion(version);\n                } else {\n                    throw new IllegalArgumentException(\"unsupported client type: \" + type);\n                }\n            }\n            ","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/naming/src/main/java/com/alibaba/nacos/naming/misc/SwitchManager.java#L123-L159","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nswitchManager.update(\"pushVersion\", \"java:v1.4\", false);\n\n// after\nswitchManager.update(\"pushVersion\", \"java:1.4.2\", false);","handlingStrategy":"validation","validationCode":"String version = \"1.4.2\"; // version segment only\nif (!version.matches(\"[0-9]+\\\\.[0-9]+\\\\.[0-9]+\")) {\n    throw new IllegalArgumentException(\"Version must be X.Y.Z\");\n}\nswitchManager.update(\"pushVersion\", \"java:\" + version, false);","typeGuard":null,"tryCatchPattern":"try {\n    switchManager.update(\"pushVersion\", value, false);\n} catch (IllegalArgumentException e) {\n    // version did not match regex — log and reject\n    logger.error(\"Invalid pushVersion segment: {}\", value);\n}","preventionTips":["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."],"tags":["naming","switch","push-version","regex","format","validation","configuration"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}