{"record":{"id":"556b156e6e121017","repo":"v2rayA/v2rayA","slug":"core-version-mismatch","errorCode":null,"errorMessage":"core version mismatch","messagePattern":"core version mismatch","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"service/kernel/v2ray/service/service.go","lineNumber":16,"sourceCode":"package service\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"os/exec\"\n\t\"strings\"\n\n\t\"github.com/v2rayA/v2rayA/common\"\n\t\"github.com/v2rayA/v2rayA/conf\"\n\t\"github.com/v2rayA/v2rayA/kernel/iptables\"\n\t\"github.com/v2rayA/v2rayA/kernel/v2ray/asset\"\n\t\"github.com/v2rayA/v2rayA/kernel/v2ray/where\"\n)\n\nvar CoreVersionMismatchError = fmt.Errorf(\"core version mismatch\")\n\nfunc IsV2rayServiceValid() bool {\n\tif !asset.DoesV2rayAssetExist(\"geoip.dat\") || !asset.DoesV2rayAssetExist(\"geosite.dat\") {\n\t\treturn false\n\t}\n\t_, ver, err := where.GetV2rayServiceVersion()\n\treturn err == nil && ver != \"\"\n}\n\nfunc IfTProxyModLoaded() bool {\n\tout, err := exec.Command(\"sh\", \"-c\", \"lsmod|grep xt_TPROXY\").Output()\n\treturn err == nil && len(bytes.TrimSpace(out)) > 0\n}\n\nfunc CheckAndProbeTProxy() (err error) {\n\tif !IfTProxyModLoaded() && !common.IsDocker() && !iptables.IsNft() { //docker下无法判断，nft不需要\n\t\tvar out []byte\n\t\tout, err = exec.Command(\"sh\", \"-c\", \"modprobe xt_TPROXY\").CombinedOutput()","sourceCodeStart":1,"sourceCodeEnd":34,"githubUrl":"https://github.com/v2rayA/v2rayA/blob/71e5442fc548c05680ee55eae943e6c0afe9ac51/service/kernel/v2ray/service/service.go#L1-L34","documentation":"CoreVersionMismatchError is the sentinel error (wrapped with %w) signaling that the v2raya_core binary's version does not match the v2rayA service version. It exists so callers can detect a mismatch specifically with errors.Is, even though the concrete message adds versions. In release builds both binaries come from the same source tree so versions must match exactly; dev builds ('debug','unstable') are exempt.","triggerScenarios":"CheckCoreVersionMatch() (called from GetVersion) reads where.GetV2rayServiceVersion(), gets coreVer != conf.Version, and neither version has a 'debug'/'unstable' prefix.","commonSituations":"Upgrading v2rayA but the core binary (v2raya_core) stayed at an old version, or vice versa; mixing binaries from different packages or manual installs; container images where only one binary was replaced.","solutions":["Upgrade v2rayA and its bundled core together (same package/image) so both binaries share one version string","Check the reported versions in the wrapped message and reinstall the older component from the same release","If developing, build with the 'debug' or 'unstable' version prefix to skip strict matching"],"exampleFix":"// caller-side detection\nif err := CheckCoreVersionMatch(); err != nil {\n    if errors.Is(err, CoreVersionMismatchError) {\n        // prompt user to update v2rayA + core together\n    }\n}","handlingStrategy":"type-guard","validationCode":"_, coreVer, err := where.GetV2rayServiceVersion()\nif err == nil && coreVer != conf.Version {\n    // trigger upgrade flow before starting the core\n}","typeGuard":"func versionsMatch() bool {\n    _, coreVer, err := where.GetV2rayServiceVersion()\n    return err == nil && (coreVer == conf.Version ||\n        common.PrefixListSatisfyString([]string{\"debug\", \"unstable\"}, coreVer) != -1 ||\n        common.PrefixListSatisfyString([]string{\"debug\", \"unstable\"}, conf.Version) != -1)\n}","tryCatchPattern":"if err := CheckCoreVersionMatch(); err != nil {\n    if errors.Is(err, CoreVersionMismatchError) {\n        // surface upgrade prompt; do not start mismatched binaries\n    }\n    return err\n}","preventionTips":["Always upgrade v2rayA and its core from the same package/image release","Pin both binaries to the same version in deployment tooling","Use errors.Is(err, CoreVersionMismatchError) rather than string matching","Build dev binaries with 'debug'/'unstable' prefixes when mixing versions"],"tags":["version-mismatch","core","upgrade","sentinel-error"],"backgroundTag":"core-version-mismatch","analyzedSha":"71e5442fc548c05680ee55eae943e6c0afe9ac51","analyzedAt":"2026-09-05T20:04:37.459Z","contentChangedAt":"2026-09-05T20:04:37.459Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}