XTLS/Xray-core · error

invalid minecraft profile username: %q

Error message

invalid minecraft profile username: %q

What it means

XMCProfile.Build validates the Minecraft profile username against ^[A-Za-z0-9_]{3,16}$ before building the xmc.Profile. This error fires when the configured username fails that regex; %q shows the exact offending value.

Source

Thrown at infra/conf/transport_finalmask.go:742

	Hostname string       `json:"hostname"`
	Profiles []XMCProfile `json:"profiles"`
	Password string       `json:"password"`
}

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
}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Set username to a real Mojang/Minecraft account name (3-16 chars, A-Z a-z 0-9 _ only)
2. Remove spaces, dashes, dots and unicode from the value
3. Confirm the field mapping: username goes to "username", the dashed UUID goes to "uuid"

Example fix

// before
"username": "Steve ##"

// after
"username": "Steve"

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

func validXmcUsername(name string) bool {
    return xmcUsernameRe.MatchString(name)
}

When it happens

Trigger: Setting an xmc (Minecraft protocol masking) transport profile username that is shorter than 3 chars, longer than 16, or contains characters outside letters/digits/underscore (spaces, dashes, unicode).

Common situations: Using a new-style username with spaces; truncating a username during copy-paste; assuming offline-mode arbitrary names are allowed; entering the UUID into the username field by mistake.

Related errors

• minecraft profiles are required
• build minecraft profile %d: %w
• not a Service.
• Dispatcher: Invalid destination.
• FakeDNSEngine is not initialized, but such a sniffer is used

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