XTLS/Xray-core · error

invalid port range: {s}

Error message

invalid port range: {s}

What it means

Returned by net.PortFromString when the string is not a parseable base-10 integer that fits uint32, i.e. strconv.ParseUint fails. It is the string-entry counterpart of the port-range check and fires before PortFromInt is even reached.

Source

Thrown at common/net/port.go:33

func PortFromBytes(port []byte) Port {
	return Port(binary.BigEndian.Uint16(port))
}

// PortFromInt converts an integer to a Port.
// @error when the integer is not positive or larger then 65535
func PortFromInt(val uint32) (Port, error) {
	if val > 65535 {
		return Port(0), errors.New("invalid port range: ", val)
	}
	return Port(val), nil
}

// PortFromString converts a string to a Port.
// @error when the string is not an integer or the integral value is a not a valid Port.
func PortFromString(s string) (Port, error) {
	val, err := strconv.ParseUint(s, 10, 32)
	if err != nil {
		return Port(0), errors.New("invalid port range: ", s)
	}
	return PortFromInt(uint32(val))
}

// Value return the corresponding uint16 value of a Port.
func (p Port) Value() uint16 {
	return uint16(p)
}

// String returns the string presentation of a Port.
func (p Port) String() string {
	return strconv.Itoa(int(p))
}

// FromPort returns the beginning port of this PortRange.
func (p *PortRange) FromPort() Port {
	return Port(p.From)
}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Use a pure numeric port string ('443', not 'https' or '443 ')
2. Trim whitespace and reject empty values before calling PortFromString
3. Add JSON-schema/config validation for port fields at load time

Example fix

// before
port, err := net.PortFromString(rawCfg.Port) // "443/tcp"

// after
port, err := net.PortFromString(strings.TrimSpace(rawCfg.Port))
if err != nil { return fmt.Errorf("invalid port %q in config", rawCfg.Port) }

s = strings.TrimSpace(s)
if _, err := strconv.ParseUint(s, 10, 16); err != nil {
    return fmt.Errorf("port %q must be 0-65535", s)
}

func isValidPortString(s string) bool { _, err := strconv.ParseUint(strings.TrimSpace(s), 10, 16); return err == nil }

When it happens

Trigger: Calling PortFromString(s) with non-numeric input ('http', '80/tcp', empty string, whitespace, negative sign, or values above 4294967295). Values between 65536 and 4294967295 parse fine here and are then rejected by PortFromInt (error 204).

Common situations: Config files where a service name was written instead of a numeric port, trailing spaces or quotes in YAML/JSON values, or environment variables that are empty by default.

Related errors

• invalid port range: {val}
• invalid port range:
• invalid port range {} -> {}
• invalid port range: {}
• invalid port: {}

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