XTLS/Xray-core · error

failed to get VLESS user

Error message

failed to get VLESS user

What it means

Thrown while creating a VLESS inbound handler: the inbound config declares a list of users, and each one is converted via user.ToMemoryUser() before being added to the MemoryValidator. This error means at least one user entry failed conversion, most commonly because its UUID string cannot be parsed into a protocol UUID. The wrapped Base(err) carries the underlying parse failure.

Source

Thrown at proxy/vless/inbound/inbound.go:64

)

func init() {
	common.Must(common.RegisterConfig((*Config)(nil), func(ctx context.Context, config interface{}) (interface{}, error) {
		var dc dns.Client
		if err := core.RequireFeatures(ctx, func(d dns.Client) error {
			dc = d
			return nil
		}); err != nil {
			return nil, err
		}

		c := config.(*Config)

		validator := new(vless.MemoryValidator)
		for _, user := range c.Users {
			u, err := user.ToMemoryUser()
			if err != nil {
				return nil, errors.New("failed to get VLESS user").Base(err).AtError()
			}
			if err := validator.Add(u); err != nil {
				return nil, errors.New("failed to initiate user").Base(err).AtError()
			}
		}

		return New(ctx, c, dc, validator)
	}))
}

// Handler is an inbound connection handler that handles messages in VLess protocol.
type Handler struct {
	inboundHandlerManager  feature_inbound.Manager
	policyManager          policy.Manager
	stats                  stats.Manager
	validator              vless.Validator
	decryption             *encryption.ServerInstance
	outboundHandlerManager outbound.Manager

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Check the wrapped error text to identify which field failed (it includes the UUID parse message)
2. Fix every clients[].id in the VLESS inbound to a canonical UUID (36 chars, 8-4-4-4-12) or a valid UUID-form input; regenerate with `xray uuid`
3. Remove placeholder/empty client entries from the inbound config
4. Validate the config with `xjson`/`xray run -test` before deploying

Example fix

// config.json (before)
"clients": [{ "id": "b831381d-6324-4d53-ad4f-8cda8b", "email": "a" }]

// after (canonical UUID, e.g. from `xray uuid`)
"clients": [{ "id": "b831381d-6324-4d53-ad4f-8cda8ba05a7", "email": "a" }]

// before starting xray, validate every VLESS inbound client UUID
import "github.com/google/uuid"

func validateVlessClients(inbounds []Inbound) error {
    for _, in := range inbounds {
        if in.Protocol != "vless" { continue }
        for _, c := range in.Settings.Clients {
            if _, err := uuid.Parse(c.ID); err != nil {
                return fmt.Errorf("inbound %s client %q: bad UUID %q: %w", in.Tag, c.Email, c.ID, err)
            }
        }
    }
    return nil
}

When it happens

Trigger: Registering a VLESS inbound whose clients[] entry has an invalid "id" (non-canonical UUID, typos, empty string), or an email/account field that fails conversion in ToMemoryUser(). Raised at handler-construction time (config load / inbound handler registration), before any traffic flows.

Common situations: Hand-edited config.json with a malformed UUID; UUIDs generated with non-standard separators or wrong length; copy-paste truncation of the id field; JSON config where id was left empty for a placeholder client.

Related errors

• VLESS users: "encryption" should not be in inbound settings
• failed to parse ID
• failed to initiate user
• Shadowsocks password is not specified.
• unknown cipher method:

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