What causes "bad profile UUID length: %d" in XTLS/Xray-core?

Supply exactly 16 bytes (e.g. base64 of the binary UUID) in the uuid field.

bad profile UUID length: %d

Error message

bad profile UUID length: %d

What it means

The profile UUID must be exactly len(UUID{}) == 16 raw bytes, because it is copied byte-for-byte into the fixed-size UUID array sent in the login/handshake packets. This error reports the actual byte length when it differs, preventing copy() from producing a truncated or zero-padded identity.

Source

Thrown at transport/internet/finalmask/xmc/profile.go:23

type loginProfile struct {
	Username          string
	UUID              UUID
	TexturesValue     string
	TexturesSignature string
}

func profilesFromConfig(configured []*Profile) ([]loginProfile, error) {
	if len(configured) == 0 {
		return nil, fmt.Errorf("empty profiles")
	}

	profiles := make([]loginProfile, 0, len(configured))
	for _, configuredProfile := range configured {
		if configuredProfile == nil || configuredProfile.Username == "" {
			return nil, fmt.Errorf("invalid profile")
		}
		if len(configuredProfile.Uuid) != len(UUID{}) {
			return nil, fmt.Errorf("bad profile UUID length: %d", len(configuredProfile.Uuid))
		}
		if configuredProfile.TexturesValue == "" || configuredProfile.TexturesSignature == "" {
			return nil, fmt.Errorf("incomplete profile textures")
		}

		profile := loginProfile{
			Username:          configuredProfile.Username,
			TexturesValue:     configuredProfile.TexturesValue,
			TexturesSignature: configuredProfile.TexturesSignature,
		}
		copy(profile.UUID[:], configuredProfile.Uuid)
		profiles = append(profiles, profile)
	}
	return profiles, nil
}

func findProfile(profiles []loginProfile, username string, uuid UUID) (loginProfile, bool) {
	for _, profile := range profiles {

View on GitHub (pinned to 7d214f8b09)

Solutions

Supply exactly 16 bytes (e.g. base64 of the binary UUID) in the uuid field.
Convert 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' by stripping hyphens, hex-decoding, and re-encoding to base64.
Log len(cfg.Uuid) locally to see which profile is malformed — the error only prints the length, not the index.

Example fix

// before (36 ASCII chars -> 36 bytes)
"uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
// after (16 raw bytes, base64)
"uuid": "Bpp59ETpRyalvvykDjiq9Q=="

Defensive patterns

Strategy: validation

Validate before calling

if len(p.Uuid) != 16 {
    return fmt.Errorf("profile %q: uuid must be 16 raw bytes, got %d", p.Username, len(p.Uuid))
}

Prevention

Store UUIDs as base64 of the 16 binary bytes, not the hyphenated string.
Convert with: b, _ := hex.DecodeString(strings.ReplaceAll(u, "-", "")) then base64.StdEncoding.EncodeToString(b).
Add a config test asserting len(Uuid)==16 for every profile.

When it happens

Trigger: Passing a UUID field whose decoded byte length is not 16: e.g. a 36-character hyphenated string used raw, a 32-char hex string, or a base64 value that decodes to another size.

Common situations: Pasting the canonical Mojang UUID format 'xxxxxxxx-xxxx-...' instead of its 16-byte binary/base64 form; mixing up offline-mode vs online-mode UUID encodings; trimming or re-encoding the field during config migration.

Related errors

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