XTLS/Xray-core · error · errors.Error

failed to parse user

Error message

failed to parse user

What it means

Returned by AddUserOperation.ApplyInbound (app/proxyman/command/command.go:49) when protocol.User.ToMemoryUser() fails while converting the protobuf user into an in-memory user. The Base error carries the protocol-specific reason — most often an unparsable or missing account message (e.g. a VMess user without a valid id UUID, or an account whose serialized message cannot be deserialized into the expected type).

Source

Thrown at app/proxyman/command/command.go:49

	if !ok {
		return nil, errors.New("can't get inbound proxy from handler.")
	}
	return gi.GetInbound(), nil
}

// ApplyInbound implements InboundOperation.
func (op *AddUserOperation) ApplyInbound(ctx context.Context, handler inbound.Handler) error {
	p, err := getInbound(handler)
	if err != nil {
		return err
	}
	um, ok := p.(proxy.UserManager)
	if !ok {
		return errors.New("proxy is not a UserManager")
	}
	mUser, err := op.User.ToMemoryUser()
	if err != nil {
		return errors.New("failed to parse user").Base(err)
	}
	return um.AddUser(ctx, mUser)
}

// ApplyInbound implements InboundOperation.
func (op *RemoveUserOperation) ApplyInbound(ctx context.Context, handler inbound.Handler) error {
	p, err := getInbound(handler)
	if err != nil {
		return err
	}
	um, ok := p.(proxy.UserManager)
	if !ok {
		return errors.New("proxy is not a UserManager")
	}
	return um.RemoveUser(ctx, op.Email)
}

type handlerServer struct {

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Inspect the chained Base error — it names the account parsing failure precisely.
2. Regenerate the user's credential (UUID for vmess/vless) with a proper generator.
3. Ensure the Account Any message's type_url matches the account proto of the target inbound's protocol.
4. Update client and server to matching xray-core versions if account protos changed.

Example fix

// before
user.Account = &anypb.Any{TypeUrl: "xray.proxy.vmess.Account", Value: badPayload}

// after — build the account with a valid UUID
account := &vmess.Account{Id: "b831381d-6324-4d53-ad4f-8cda48b30811"}
user.Account = serial.ToTypedMessage(account)

// validate credentials before sending AddUser
if _, err := uuid.Parse(user.Id); err != nil {
    return fmt.Errorf("invalid UUID %q for user %q", user.Id, user.Email)
}

if err := addOp.ApplyInbound(ctx, handler); err != nil {
    if strings.Contains(err.Error(), "failed to parse user") { rejectUserPayload(user) } else { return err }
}

When it happens

Trigger: Calling AddUser with a User whose Account's type_url does not match any registered account proto, or whose payload fails validation: invalid UUID for VMess/VLESS, malformed password encoding, or empty account.

Common situations: Panels generating bad UUIDs (wrong length, non-hex characters), missing the account entirely, or version skew where the client's proto enum for the account type differs from the server's.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• proxy is not a UserManager
• can't get inbound proxy from handler.
• unknown operation
• not an inbound operation
• failed to get handler:

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