XTLS/Xray-core · error

version != 2

Error message

version != 2

What it means

Thrown by HysteriaConfig.Build() when the config's version field is not 2. The core only implements the Hysteria2 protocol; version 1 configs are not buildable, and a missing/zero version also fails since 0 != 2.

Source

Thrown at infra/conf/transport_method.go:776

	StatusCode int32             `json:"statusCode"`
}

type HysteriaConfig struct {
	Version int32  `json:"version"`
	Auth    string `json:"auth"`

	Congestion *string    `json:"congestion"`
	Up         *Bandwidth `json:"up"`
	Down       *Bandwidth `json:"down"`
	UdpHop     *UdpHop    `json:"udphop"`

	UdpIdleTimeout int64      `json:"udpIdleTimeout"`
	Masquerade     Masquerade `json:"masquerade"`
}

func (c *HysteriaConfig) Build() (proto.Message, error) {
	if c.Version != 2 {
		return nil, errors.New("version != 2")
	}

	if c.Congestion != nil || c.Up != nil || c.Down != nil || c.UdpHop != nil {
		errors.LogWarning(context.Background(), "congestion & up & down & udphop move to finalmask/quicParams")
	}

	if c.UdpIdleTimeout != 0 && (c.UdpIdleTimeout < 2 || c.UdpIdleTimeout > 600) {
		return nil, errors.New("UdpIdleTimeout must be between 2 and 600")
	}

	config := &hysteria.Config{}
	config.Auth = c.Auth
	config.UdpIdleTimeout = c.UdpIdleTimeout
	config.MasqType = c.Masquerade.Type
	config.MasqFile = c.Masquerade.Dir
	config.MasqUrl = c.Masquerade.Url
	config.MasqUrlRewriteHost = c.Masquerade.RewriteHost
	config.MasqUrlInsecure = c.Masquerade.Insecure

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Set "version": 2 in the hysteria settings block.
2. If you genuinely need Hysteria1, run the standalone Hysteria1 server/client instead of this core.

Example fix

// before
"hysteriaSettings": { "servers": [ ... ] } // version missing
// after
"hysteriaSettings": { "version": 2, "servers": [ ... ] }

if h.Version != 2 {
    return errors.New("only hysteria version 2 is supported")
}

When it happens

Trigger: Supplying a hysteria transport block with "version": 1 or omitting the version field entirely.

Common situations: Porting a Hysteria1 config to Xray, or writing a new hysteria block from a tutorial that predates the version requirement.

Related errors

• Failed to build Hysteria config.
• unsupported unit:
• UdpIdleTimeout must be between 2 and 600
• bridge tag is empty
• bridge domain is empty

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