XTLS/Xray-core · error

version != 2

Error message

version != 2

What it means

Thrown by HysteriaClientConfig.Build when the hysteria outbound's version field is not exactly 2. Xray's hysteria implementation only supports Hysteria2; the version field is a hard gate on the client side. Both an omitted version (zero default) and version: 1 fail here.

Source

Thrown at infra/conf/hysteria.go:21

import (
	"github.com/xtls/xray-core/common/errors"
	"github.com/xtls/xray-core/common/protocol"
	"github.com/xtls/xray-core/common/serial"
	"github.com/xtls/xray-core/common/task"
	"github.com/xtls/xray-core/proxy/hysteria"
	"github.com/xtls/xray-core/proxy/hysteria/account"
	"google.golang.org/protobuf/proto"
)

type HysteriaClientConfig struct {
	Version int32    `json:"version"`
	Address *Address `json:"address"`
	Port    uint16   `json:"port"`
}

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

	config := &hysteria.ClientConfig{}
	config.Server = &protocol.ServerEndpoint{
		Address: c.Address.Build(),
		Port:    uint32(c.Port),
	}

	return config, nil
}

type HysteriaUserConfig struct {
	Auth  string `json:"auth"`
	Level uint32 `json:"level"`
	Email string `json:"email"`
}

type HysteriaServerConfig struct {

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Set "version": 2 in the hysteria outbound settings
2. If you actually have a Hysteria1 server, migrate the server to Hysteria2 or use a client that supports v1

Example fix

// before
{ "protocol": "hysteria", "settings": { "address": "h.example.com", "port": 443 } }
// after
{ "protocol": "hysteria", "settings": { "version": 2, "address": "h.example.com", "port": 443 } }

if hysteriaSettings.Version != 2 {
	return errors.New("hysteria outbound requires version: 2")
}

When it happens

Trigger: Adding a hysteria outbound without "version": 2 in settings, or explicitly setting version to 1 or 3.

Common situations: Copying a Hysteria1 config from another client (original hysteria uses different fields); assuming version is optional with a sane default; forgetting the field when hand-writing outbounds.

Related errors

• unsupported domain strategy: {}
• invalid redirect address: {}
• invalid redirect port: {}
• HTTP settings: "servers" should have one and only one member
• Failed to build Hysteria config.

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