XTLS/Xray-core · error

minecraft finalmask: %w

Error message

minecraft finalmask: %w

What it means

Config.WrapConnClient failed while parsing Config.Profiles via profilesFromConfig, before any network I/O. The wrapped error is the profile validation failure (nil/empty profile list, empty username, zero/invalid UUID, or duplicate entries depending on profile.go's checks). The connection is never established; this is a local config error.

Source

Thrown at transport/internet/finalmask/xmc/config.go:14

package xmc

import (
	"fmt"
	"net"
)

func (c *Config) TCP() {
}

func (c *Config) WrapConnClient(conn net.Conn) (net.Conn, error) {
	profiles, err := profilesFromConfig(c.Profiles)
	if err != nil {
		return nil, fmt.Errorf("minecraft finalmask: %w", err)
	}
	cc, err := newClientConn(conn, profiles, c.Password, c.RsaPublicKey, c.Hostname)
	if err != nil {
		return nil, fmt.Errorf("minecraft finalmask: %w", err)
	}

	return cc, nil
}

func (c *Config) WrapConnServer(conn net.Conn) (net.Conn, error) {
	profiles, err := profilesFromConfig(c.Profiles)
	if err != nil {
		return nil, fmt.Errorf("minecraft finalmask: %w", err)
	}
	cc, err := wrapConnServer(conn, profiles, c.Password, c.RsaPrivateKey, c.RsaPublicKey)
	if err != nil {
		return nil, fmt.Errorf("minecraft finalmask: %w", err)
	}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Inspect the wrapped error text — it names the exact profile field that is invalid
2. Populate Config.Profiles with at least one entry carrying a non-empty Username and a valid UUID
3. Validate the profile list at startup before enabling the outbound (see validationCode)

Example fix

// before
cfg := &xmc.Config{Password: pw, RsaPublicKey: der} // Profiles omitted -> error

// after
cfg := &xmc.Config{
    Password:     pw,
    RsaPublicKey: der,
    Profiles:     []*xmc.Profile{{Username: "player1", Uuid: "069a79f4-44e9-4726-a5be-fca90e38aaf5"}},
}

func validateXmcProfiles(ps []*xmc.Profile) error {
    if len(ps) == 0 {
        return errors.New("xmc: at least one profile required")
    }
    for i, p := range ps {
        if p.Username == "" {
            return fmt.Errorf("xmc: profile[%d] missing username", i)
        }
        if _, err := uuid.Parse(p.Uuid); err != nil {
            return fmt.Errorf("xmc: profile[%d] bad uuid: %w", i, err)
        }
    }
    return nil
}

wrapped, err := cfg.WrapConnClient(conn)
if err != nil {
    if strings.HasPrefix(err.Error(), "minecraft finalmask:") && !strings.Contains(err.Error(), "rsa") {
        return fmt.Errorf("invalid xmc profiles config: %w", err)
    }
    return err
}

When it happens

Trigger: Calling WrapConnClient with a Config whose Profiles are nil, contain an entry with an empty Username, or carry a malformed UUID; profilesFromConfig returns the error and it is prefixed with 'minecraft finalmask:'.

Common situations: JSON/protobuf config where the profiles array was omitted, partially filled, or UUIDs pasted with braces/hyphens in a format the parser rejects; shared templates that forget to override the profiles block.

Related errors

• bridge tag is empty
• bridge domain is empty
• portal tag is empty
• portal domain is empty
• unknown action: {}

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