XTLS/Xray-core · error

invalid randRange

Error message

invalid randRange

What it means

HeaderCustomTCP.Build (infra/conf/transport_finalmask.go:129-145) validates each clients[i][j].randRange before converting it into custom.TCPSequence bytes. randRange defaults to {from:0,to:255} when omitted, and any explicit range with from<0 or to>255 is rejected with "invalid randRange" because it indexes individual bytes of a TCP payload.

Source

Thrown at infra/conf/transport_finalmask.go:129

			}
		}
	}
	for _, value := range c.Servers {
		for _, item := range value {
			if err := validateCustomItemSpec(item.Capture, item.Packet, item.Rand, item.Reuse, item.Transform); err != nil {
				return nil, err
			}
		}
	}
	for _, value := range c.Errors {
		for _, item := range value {
			if err := validateCustomItemSpec(item.Capture, item.Packet, item.Rand, item.Reuse, item.Transform); err != nil {
				return nil, err
			}
		}
	}

	errInvalidRange := errors.New("invalid randRange")

	clients := make([]*custom.TCPSequence, len(c.Clients))
	for i, value := range c.Clients {
		clients[i] = &custom.TCPSequence{}
		for _, item := range value {
			if item.RandRange == nil {
				item.RandRange = &Int32Range{From: 0, To: 255}
			}
			if item.RandRange.From < 0 || item.RandRange.To > 255 {
				return nil, errInvalidRange
			}
			var err error
			if item.Packet, err = PraseByteSlice(item.Packet, item.Type); err != nil {
				return nil, err
			}
			transform, err := buildCustomTransform(item.Transform)
			if err != nil {
				return nil, err

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Keep randRange within 0..255 inclusive, e.g. {"from":32,"to":126}
2. Omit randRange entirely to accept the 0-255 default
3. Use "rand" (count of random bytes) for length control, not randRange

Example fix

// before
"randRange": { "from": 0, "to": 65535 }
// after
"randRange": { "from": 0, "to": 255 }

for (const seq of cfg.clients ?? []) for (const it of seq) {
  const rr = it.randRange ?? {from:0, to:255};
  if (rr.from < 0 || rr.to > 255) throw new Error(`randRange must be within 0-255, got ${rr.from}-${rr.to}`);
}

const inByteRange = (r:{from:number;to:number}) => r.from >= 0 && r.to <= 255;

When it happens

Trigger: A tcpmask "header-custom" clients entry with "randRange":{"from":-1,...} or {"to":256}; also any typo making To parse large. Only the clients loop shown validates (servers/errors items go through the same builder path with their own defaults).

Common situations: Users assuming randRange is a packet-length range in bytes (thousands) rather than a per-byte value range 0-255; copying rand semantics from the "rand" count field; negative "from" copied from delay ranges where negatives are tolerated.

Related errors

• invalid variable name
• exactly one item kind must be set
• transform op is required
• transform args are required
• transform arg must set exactly one value

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