XTLS/Xray-core · error

invalid port range {} -> {}

Error message

invalid port range {} -> {}

What it means

Thrown by PortRange.UnmarshalJSON in infra/conf/common.go when a string-form port range parses but is inconsistent: either From > To (reversed range like "9000-8000") or To exceeds 65535 (the max TCP/UDP port). The message interpolates the concrete From -> To values.

Source

Thrown at infra/conf/common.go:204

		return fmt.Sprintf("%d-%d", port.From, port.To)
	}
}

// UnmarshalJSON implements encoding/json.Unmarshaler.UnmarshalJSON
func (v *PortRange) UnmarshalJSON(data []byte) error {
	port, err := parseIntPort(data)
	if err == nil {
		v.From = uint32(port)
		v.To = uint32(port)
		return nil
	}

	from, to, err := parseJSONStringPort(data)
	if err == nil {
		v.From = uint32(from)
		v.To = uint32(to)
		if v.From > v.To || v.To > math.MaxUint16 {
			return errors.New("invalid port range ", v.From, " -> ", v.To)
		}
		return nil
	}

	return errors.New("invalid port range: ", string(data))
}

type PortList struct {
	Range []PortRange
}

func (list *PortList) Build() *net.PortList {
	portList := new(net.PortList)
	for _, r := range list.Range {
		portList.Range = append(portList.Range, r.Build())
	}
	return portList
}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Fix the range so From <= To and To <= 65535: "port": "8000-9000"
2. If you meant a single port, use a plain integer: "port": 443
3. For env-driven ranges, print the resolved variable and correct it

Example fix

// before
"port": "9000-8000"

// after
"port": "8000-9000"

func validatePortRange(from, to int) error {
    if from > to {
        return fmt.Errorf("range reversed: %d -> %d", from, to)
    }
    if to > 65535 || from < 1 {
        return fmt.Errorf("ports must be 1-65535, got %d-%d", from, to)
    }
    return nil
}

if err := json.Unmarshal(data, &pr); err != nil {
    if strings.Contains(err.Error(), "invalid port range") {
        return fmt.Errorf("port range %s: ensure from <= to and to <= 65535", data)
    }
    return err
}

When it happens

Trigger: "port": "9000-8000" (reversed), "port": "1-70000" (upper bound over MaxUint16), or an env: variable resolving to such a range. Both parseIntPort (single int) and parseJSONStringPort succeed at parsing, then the consistency check fails.

Common situations: Port scanners / proxy chains configured with large ephemeral ranges (e.g. 49152-65535 is fine but typos like 65635 appear); reversed ranges from copy-paste; env vars like $REMOTE_PORT_RANGE misconfigured.

Related errors

• invalid port range:
• invalid port range: {}
• invalid port: {}
• invalid portMap: {}
• invalid redirect port: {}

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