XTLS/Xray-core · error

invalid minecraft profile UUID: %w

Error message

invalid minecraft profile UUID: %w

What it means

XMCProfile.Build parses the profile's UUID with googleuuid.Parse; any parse failure is wrapped as this error. Both the dashed 36-char form and the raw 32-hex-digit form are accepted by that parser.

Source

Thrown at infra/conf/transport_finalmask.go:747

type XMCProfile struct {
	// Resolve the UUID by username, then request the session profile with
	// unsigned=false. Client and server must use the same signed profile.
	Username          string `json:"username"`
	UUID              string `json:"uuid"`
	TexturesValue     string `json:"texturesValue"`
	TexturesSignature string `json:"texturesSignature"`
}

var xmcUsernamePattern = regexp.MustCompile(`^[A-Za-z0-9_]{3,16}$`)

func (c *XMCProfile) Build() (*xmc.Profile, error) {
	if !xmcUsernamePattern.MatchString(c.Username) {
		return nil, fmt.Errorf("invalid minecraft profile username: %q", c.Username)
	}

	profileUUID, err := googleuuid.Parse(c.UUID)
	if err != nil {
		return nil, fmt.Errorf("invalid minecraft profile UUID: %w", err)
	}
	if c.TexturesValue == "" || c.TexturesSignature == "" {
		return nil, fmt.Errorf("incomplete minecraft profile textures")
	}

	return &xmc.Profile{
		Username:          c.Username,
		Uuid:              append([]byte(nil), profileUUID[:]...),
		TexturesValue:     c.TexturesValue,
		TexturesSignature: c.TexturesSignature,
	}, nil
}

func (c *XMC) Build() (proto.Message, error) {
	if len(c.Profiles) == 0 {
		return nil, fmt.Errorf("minecraft profiles are required")
	}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Paste the full UUID from the official session/profile lookup for that username
2. If using the undashed form, ensure exactly 32 hex characters
3. Strip whitespace and smart quotes around the value
4. Verify with an online UUID parser or `uuid.Parse` in a scratch program

Example fix

// before
"uuid": "069a79f44c9b4d5f8f5f9f5f5f5f5f5f5f5f" // 34 chars, invalid

// after
"uuid": "069a79f4-4c9b-4d5f-8f5f-9f5f5f5f5f5f"

import "github.com/google/uuid"

func validProfileUUID(s string) bool {
    _, err := uuid.Parse(strings.TrimSpace(s))
    return err == nil
}

When it happens

Trigger: Setting the xmc profile "uuid" to a non-UUID string (wrong length, non-hex characters, mangled dashes) or leaving it empty.

Common situations: Copying a Mojang profile URL id that is actually the trimmed undashed UUID with a character missing; using the username in the uuid field; trailing whitespace/newlines from copy-paste.

Related errors

• invalid minecraft profile username: %q
• incomplete minecraft profile textures
• minecraft profiles are required
• build minecraft profile %d: %w
• bad profile UUID length: %d

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