{"record":{"id":"865b7ff59e2475cd","repo":"XTLS/Xray-core","slug":"this-config-must-be-run-on-version-s-or-higher","errorCode":null,"errorMessage":"this config must be run on version %s or higher","messagePattern":"this config must be run on version (.+?) or higher","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"app/version/version.go","lineNumber":24,"sourceCode":"\t\"strings\"\n\n\t\"github.com/xtls/xray-core/common\"\n\t\"github.com/xtls/xray-core/common/errors\"\n)\n\ntype Version struct {\n\tconfig *Config\n\tctx    context.Context\n}\n\nfunc New(ctx context.Context, config *Config) (*Version, error) {\n\tif config.MinVersion != \"\" {\n\t\tresult, err := compareVersions(config.MinVersion, config.CoreVersion)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tif result > 0 {\n\t\t\treturn nil, errors.New(\"this config must be run on version \", config.MinVersion, \" or higher\")\n\t\t}\n\t}\n\tif config.MaxVersion != \"\" {\n\t\tresult, err := compareVersions(config.MaxVersion, config.CoreVersion)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tif result < 0 {\n\t\t\treturn nil, errors.New(\"this config should be run on version \", config.MaxVersion, \" or lower\")\n\t\t}\n\t}\n\treturn &Version{config: config, ctx: ctx}, nil\n}\n\nfunc compareVersions(v1, v2 string) (int, error) {\n\t// Split version strings into components\n\tv1Parts := strings.Split(v1, \".\")\n\tv2Parts := strings.Split(v2, \".\")","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/app/version/version.go#L6-L42","documentation":"Returned by version.New during config validation when the config declares a MinVersion strictly greater than the running core version (config.CoreVersion). It is a compatibility gate: the config author states the minimum core build required, and the process refuses to start on an older core. The required version string is interpolated into the message.","triggerScenarios":"Starting Xray with a JSON/config that sets a minVersion (e.g. generated by a newer panel) while the installed xray binary reports a lower semantic version; compareVersions(MinVersion, CoreVersion) > 0.","commonSituations":"Upgrading a panel/config template before upgrading the xray binary; downgrading xray-core for stability while keeping newer configs; version strings with differing component counts are padded with zeros, so '5.2' vs '5.2.0' compare equal but '5.3' vs '5.2.8' fails.","solutions":["Upgrade the xray-core binary to at least the version named in the error message (e.g. 'xray version' to verify, then replace the binary).","If the config was authored for you and the minVersion is overly strict, edit the config's minVersion down to your actual core version.","After upgrading, confirm core reports the new version (xray version) and restart."],"exampleFix":"// before (config)\n\"minVersion\": \"25.9.30\" // core is 24.12.18 -> startup fails\n\n// after\n# upgrade core, or lower the floor:\n\"minVersion\": \"24.12.18\"","handlingStrategy":"validation","validationCode":"// Compare versions before starting the core:\nif cfg.MinVersion != \"\" {\n    if c, err := versionCompare(cfg.MinVersion, coreVer); err == nil && c > 0 {\n        log.Fatalf(\"upgrade xray core to >= %s\", cfg.MinVersion)\n    }\n}","typeGuard":"func isNumericVersion(v string) bool {\n    if v == \"\" { return false }\n    for _, p := range strings.Split(v, \".\") {\n        if _, err := strconv.Atoi(p); err != nil { return false }\n    }\n    return true\n}","tryCatchPattern":"_, err := version.New(ctx, vcfg)\nif err != nil { /* abort startup, surface 'must be run on version X or higher' to operator */ }","preventionTips":["Upgrade core and config templates together","Verify with 'xray version' before deploying configs from newer panels"],"tags":["version","config","startup","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}