XTLS/Xray-core · error

unsupported session placement:

Error message

unsupported session placement: 

What it means

SplitHTTPConfig.Build() validates "sessionIDPlacement" at transport_method.go:383-389. Empty defaults to "path"; only "path", "cookie", "header", "query" are accepted; other values are appended to the error. Session ID placement controls where the per-connection session identifier travels.

Source

Thrown at infra/conf/transport_method.go:388

	default:
		return nil, errors.New("unsupported uplink data placement: " + c.UplinkDataPlacement)
	}

	if c.UplinkHTTPMethod == "" {
		c.UplinkHTTPMethod = "POST"
	}
	c.UplinkHTTPMethod = strings.ToUpper(c.UplinkHTTPMethod)

	if c.UplinkHTTPMethod == "GET" && c.Mode != "packet-up" {
		return nil, errors.New("uplinkHTTPMethod can be GET only in packet-up mode")
	}

	switch c.SessionIDPlacement {
	case "":
		c.SessionIDPlacement = "path"
	case "path", "cookie", "header", "query":
	default:
		return nil, errors.New("unsupported session placement: " + c.SessionIDPlacement)
	}

	switch c.SeqPlacement {
	case "":
		c.SeqPlacement = "path"
	case "path", "cookie", "header", "query":
	default:
		return nil, errors.New("unsupported seq placement: " + c.SeqPlacement)
	}

	if c.SessionIDPlacement != "path" && c.SessionIDKey == "" {
		switch c.SessionIDPlacement {
		case "cookie", "query":
			c.SessionIDKey = "x_session"
		case "header":
			c.SessionIDKey = "X-Session"
		}
	}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Use one of: "path", "cookie", "header", "query"
2. Omit the field to use the "path" default

Example fix

// before
"sessionIDPlacement": "queryInHeader"
// after
"sessionIDPlacement": "query"

func validSessionPlacement(p string) bool {
	switch p {
	case "", "path", "cookie", "header", "query":
		return true
	}
	return false
}

When it happens

Trigger: "sessionIDPlacement": "Path", "url", "pathInQuery", or any string outside the four allowed values in splithttp transportSettings.

Common situations: Typos and casing mistakes; confusion with xPaddingPlacement's "queryInHeader" value which is NOT valid here.

Related errors

• sessionIDTable or sessionIDLength is too small
• sessionIDLength.from must be greater than 0
• sessionIDTable must contain only ASCII characters
• Failed to unmarshal "extra".
• unsupported mode:

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