What causes "invalid scheme + u.Scheme" in XTLS/Xray-core?

Change the url scheme to 'realm://' for TLS-backed (https) transport.

invalid scheme + u.Scheme

Error message

invalid scheme + u.Scheme

What it means

Thrown by Realm.Build() while parsing the Realm transport 'url' field: only two schemes are accepted, 'realm' (mapped to https) and 'realm+http' (mapped to http). Any other URL scheme is rejected before host/port/token/id extraction begins.

Source

Thrown at infra/conf/transport_finalmask.go:840

}

func (c *Realm) Build() (proto.Message, error) {
	var scheme, host, port, token, id string
	var stunServers []string
	var tlsConfig *tls.Config

	u, err := url.Parse(c.Url)
	if err != nil {
		return nil, err
	}

	switch u.Scheme {
	case "realm":
		scheme = "https"
	case "realm+http":
		scheme = "http"
	default:
		return nil, errors.New("invalid scheme", u.Scheme)
	}

	host = u.Hostname()
	if host == "" {
		return nil, errors.New("invalid host", host)
	}

	port = u.Port()
	if port == "" {
		port = "443"
		if scheme == "http" {
			port = "80"
		}
	}

	token, err = url.PathUnescape(u.User.String())
	if err != nil {
		return nil, err

View on GitHub (pinned to 7d214f8b09)

Solutions

Change the url scheme to 'realm://' for TLS-backed (https) transport.
Use 'realm+http://' for plaintext (http) transport.
Double-check for scheme typos and stray characters before the ':'.

Example fix

// before
"url": "https://mytoken@signal.example.com:8443/v1"
// after
"url": "realm://mytoken@signal.example.com:8443/v1"

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.Parse(raw)
if err != nil || (u.Scheme != "realm" && u.Scheme != "realm+http") {
    return fmt.Errorf("url must use realm:// or realm+http:// scheme")
}

Prevention

Never feed plain https:// URLs to the Realm transport field.
Centralize Realm URL construction in one helper that enforces the scheme.
Pre-flight parse every URL field with net/url before handing config to the core.

When it happens

Trigger: Setting url to "https://token@host:port/id" or "realm://..." variants with a typo like "realms+http://" triggers this. The value must literally start with realm: or realm+http:.

Common situations: Pasting a conventional https:// URL instead of the realm scheme; typos in the scheme; URLs left empty or malformed after template substitution so url.Parse yields an unexpected scheme.

Related errors

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