What causes "failed to parse ID" in XTLS/Xray-core?

Regenerate the id with `xray uuid` and paste it exactly into both client and server

failed to parse ID

Error message

failed to parse ID

What it means

When a VLESS inbound/outbound account is instantiated, the configured Id string must parse as a UUID (uuid.ParseString). Failure returns this error at error severity. Common base causes: typo (wrong character, e.g. 'g'-'z' are invalid in hex UUIDs), wrong length, dashes missing or misplaced, empty string, or a copied UUID with invisible whitespace/quotes.

Source

Thrown at proxy/vless/account.go:15

package vless

import (
	"google.golang.org/protobuf/proto"

	"github.com/xtls/xray-core/common/errors"
	"github.com/xtls/xray-core/common/protocol"
	"github.com/xtls/xray-core/common/uuid"
)

// AsAccount implements protocol.Account.AsAccount().
func (a *Account) AsAccount() (protocol.Account, error) {
	id, err := uuid.ParseString(a.Id)
	if err != nil {
		return nil, errors.New("failed to parse ID").Base(err).AtError()
	}
	return &MemoryAccount{
		ID:         protocol.NewID(id),
		Flow:       a.Flow,       // needs parser here?
		Encryption: a.Encryption, // needs parser here?
		XorMode:    a.XorMode,
		Seconds:    a.Seconds,
		Padding:    a.Padding,
		Reverse:    a.Reverse,
		Testpre:    a.Testpre,
		Testseed:   a.Testseed,
	}, nil
}

// MemoryAccount is an in-memory form of VLess account.
type MemoryAccount struct {
	// ID of the account.
	ID *protocol.ID

View on GitHub (pinned to 7d214f8b09)

Solutions

Regenerate the id with `xray uuid` and paste it exactly into both client and server
Trim whitespace/newlines and verify the string against canonical 8-4-4-4-12 hex format
Ensure both peers use the identical id

Example fix

// before
"id": "b831381d-6324-4d53-ad4f-8cda48b3081g "

// after
"id": "b831381d-6324-4d53-ad4f-8cda48b30811"

Defensive patterns

Strategy: validation

Validate before calling

func isValidXrayID(id string) bool {
	_, err := uuid.ParseString(id)
	return err == nil
}

if !isValidXrayID(cfg.Id) {
	log.Fatalf("invalid vless id %q (generate with `xray uuid`)", cfg.Id)
}

Type guard

func isVLESSId(v string) bool {
	if len(v) != 36 { return false }
	for i, c := range v {
		switch i {
		case 8, 13, 18, 23:
			if c != '-' { return false }
		default:
			if !((c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F')) { return false }
		}
	}
	return true
}

Try / catch

acct, err := rawAccount.AsAccount()
if err != nil {
	if strings.Contains(err.Error(), "failed to parse ID") {
		// regenerate id via uuid.New() and rewrite config
	}
	return err
}

Prevention

Generate ids with `xray uuid` or uuid.New()
Copy ids without trailing whitespace or quotes
Keep client and server ids byte-identical

When it happens

Trigger: VLESS client/server config with an id like "b831381d-6324-4d53-ad4f-8cda48b3081g" (invalid hex char), truncated UUID, or ""; provisioning pipelines that generate non-canonical UUID strings; JSON escaping issues adding quotes into the value.

Common situations: Hand-edited configs; copy-paste from tutorials introducing whitespace; scripts that format UUIDv7 or ULIDs (not accepted); trailing newline in env-provided id.

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

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