XTLS/Xray-core · critical

this config must be run on version %s or higher

Error message

this config must be run on version %s or higher

What it means

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.

Source

Thrown at app/version/version.go:24

	"strings"

	"github.com/xtls/xray-core/common"
	"github.com/xtls/xray-core/common/errors"
)

type Version struct {
	config *Config
	ctx    context.Context
}

func New(ctx context.Context, config *Config) (*Version, error) {
	if config.MinVersion != "" {
		result, err := compareVersions(config.MinVersion, config.CoreVersion)
		if err != nil {
			return nil, err
		}
		if result > 0 {
			return nil, errors.New("this config must be run on version ", config.MinVersion, " or higher")
		}
	}
	if config.MaxVersion != "" {
		result, err := compareVersions(config.MaxVersion, config.CoreVersion)
		if err != nil {
			return nil, err
		}
		if result < 0 {
			return nil, errors.New("this config should be run on version ", config.MaxVersion, " or lower")
		}
	}
	return &Version{config: config, ctx: ctx}, nil
}

func compareVersions(v1, v2 string) (int, error) {
	// Split version strings into components
	v1Parts := strings.Split(v1, ".")
	v2Parts := strings.Split(v2, ".")

View on GitHub (pinned to 7d214f8b09)

Solutions

1. 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).
2. If the config was authored for you and the minVersion is overly strict, edit the config's minVersion down to your actual core version.
3. After upgrading, confirm core reports the new version (xray version) and restart.

Example fix

// before (config)
"minVersion": "25.9.30" // core is 24.12.18 -> startup fails

// after
# upgrade core, or lower the floor:
"minVersion": "24.12.18"

// Compare versions before starting the core:
if cfg.MinVersion != "" {
    if c, err := versionCompare(cfg.MinVersion, coreVer); err == nil && c > 0 {
        log.Fatalf("upgrade xray core to >= %s", cfg.MinVersion)
    }
}

func isNumericVersion(v string) bool {
    if v == "" { return false }
    for _, p := range strings.Split(v, ".") {
        if _, err := strconv.Atoi(p); err != nil { return false }
    }
    return true
}

_, err := version.New(ctx, vcfg)
if err != nil { /* abort startup, surface 'must be run on version X or higher' to operator */ }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• this config should be run on version %s or lower
• version != 2
• failed to parse yaml config
• failed to load config files: [
• failed to create server

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/865b7ff59e2475cd. Report an issue: GitHub.