XTLS/Xray-core · error

sessionIDTable must contain only ASCII characters

Error message

sessionIDTable must contain only ASCII characters

What it means

Inside the sessionIDTable block, SplitHTTPConfig.Build() scans every byte of the (predefined-resolved) table and rejects any byte >= 0x80 at transport_method.go:420-424. Session IDs built from the table end up in URLs, cookies, and headers, so the alphabet must be 7-bit ASCII.

Source

Thrown at infra/conf/transport_method.go:422

			c.SessionIDKey = "X-Session"
		}
	}

	if c.SessionIDTable != "" {
		if predefined, ok := splithttp.PredefinedTable[c.SessionIDTable]; ok {
			c.SessionIDTable = predefined
		}
		room := roomSize(len(c.SessionIDTable), c.SessionIDLength.From, c.SessionIDLength.To)
		// 2.1B possiblities should be enough
		if room.Cmp(big.NewInt(2<<30)) < 0 {
			return nil, errors.New("sessionIDTable or sessionIDLength is too small")
		}
		if c.SessionIDLength.From <= 0 {
			return nil, errors.New("sessionIDLength.from must be greater than 0")
		}
		for i := 0; i < len(c.SessionIDTable); i++ {
			if c.SessionIDTable[i] >= 0x80 {
				return nil, errors.New("sessionIDTable must contain only ASCII characters")
			}
		}
	}

	if c.SeqPlacement != "path" && c.SeqKey == "" {
		switch c.SeqPlacement {
		case "cookie", "query":
			c.SeqKey = "x_seq"
		case "header":
			c.SeqKey = "X-Seq"
		}
	}

	if c.UplinkDataPlacement != splithttp.PlacementBody && c.UplinkDataKey == "" {
		switch c.UplinkDataPlacement {
		case splithttp.PlacementCookie:
			c.UplinkDataKey = "x_data"
		case splithttp.PlacementAuto, splithttp.PlacementHeader:

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Restrict "sessionIDTable" to ASCII bytes 0x00-0x7F (practically: alphanumeric plus URL-safe symbols)
2. Use a named predefined table from splithttp.PredefinedTable instead of a custom string
3. Re-save the config as plain UTF-8 without BOM/smart quotes

Example fix

// before
"sessionIDTable": "aàbçdé"
// after
"sessionIDTable": "abcdefghijklmnopqrstuvwxyz0123456789"

// Go: ASCII-only table check before Build()
for i := 0; i < len(cfg.SessionIDTable); i++ {
	if cfg.SessionIDTable[i] >= 0x80 {
		return errors.New("sessionIDTable must be 7-bit ASCII")
	}
}

When it happens

Trigger: A custom "sessionIDTable" containing non-ASCII characters, e.g. "abc你好" or any accented/cyrillic/emoji character, after PredefinedTable lookup did not match (custom tables are used verbatim).

Common situations: Users pasting 'random-looking' unicode strings as tables; configs saved in encodings that introduce smart quotes or BOM characters.

Related errors

• unsupported session placement:
• sessionIDTable or sessionIDLength is too small
• sessionIDLength.from must be greater than 0
• Failed to unmarshal "extra".
• unsupported mode:

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