XTLS/Xray-core · error

failed to initiate user

Error message

failed to initiate user

What it means

Thrown during VLESS inbound handler creation when MemoryValidator.Add(u) rejects a user that already passed ToMemoryUser(). The validator indexes users by UUID (and email), so this fires on duplicate registration inside one inbound — the second Add with the same key fails.

Source

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

	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
	observer               features.Feature
	defaultDispatcher      routing.Dispatcher
	ctx                    context.Context

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Look at the wrapped validator error to see which key (id/email) collided
2. Give every clients[] entry in the same inbound a distinct UUID and distinct email
3. If the same user must appear in two inbounds, that is allowed — only duplicates within one inbound are rejected
4. Regenerate ids with `xray uuid` per client

Example fix

// before — duplicate id in one inbound
"clients": [
  { "id": "b831381d-...-8ba05a7", "email": "a" },
  { "id": "b831381d-...-8ba05a7", "email": "b" }
]

// after — unique ids
"clients": [
  { "id": "b831381d-...-8ba05a7", "email": "a" },
  { "id": "f67e1a20-...-c4d9e6f", "email": "b" }
]

func checkDuplicateClients(inbound Inbound) error {
    seenID := map[string]string{}
    for _, c := range inbound.Settings.Clients {
        if prev, dup := seenID[c.ID]; dup {
            return fmt.Errorf("duplicate UUID shared by %q and %q", prev, c.Email)
        }
        seenID[c.ID] = c.Email
    }
    return nil
}

When it happens

Trigger: Two clients[] entries in the same VLESS inbound share the same "id" (UUID), or the same email is reused in a way the validator rejects; occurs at startup while the handler builds its user table.

Common situations: Copying a client block to add a new user and forgetting to change the id; merging inbound configs that each contained the same default UUID; automated provisioning scripts that assign a fixed UUID.

Related errors

• VLESS users: "encryption" should not be in inbound settings
• failed to get VLESS user
• existing tag found: ${tag}
• Shadowsocks password is not specified.
• unknown cipher method:

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