sgl-project/sglang · error · ValueError

{field_name} port must be between 0 and 65535: {port}

Error message

{field_name} port must be between 0 and 65535: {port}

What it means

Thrown by parse_tcp_host_port when the parsed port integer falls outside 0–65535, the valid TCP port range enforced by the function.

Source

Thrown at python/sglang/multimodal_gen/runtime/utils/common.py:149

    try:
        host, port_str = addr.rsplit(":", 1)
    except ValueError as exc:
        raise ValueError(
            f"{field_name} must be formatted as tcp://host:port or host:port"
        ) from exc

    host = host.strip()
    port_str = port_str.strip()
    if not host or not port_str:
        raise ValueError(f"{field_name} must include both host and port: {value!r}")

    try:
        port = int(port_str)
    except ValueError as exc:
        raise ValueError(f"{field_name} port must be an integer: {port_str}") from exc

    if port < 0 or port > 65535:
        raise ValueError(f"{field_name} port must be between 0 and 65535: {port}")
    return host, port


def format_tcp_endpoint(host: str, port: int, field_name: str) -> str:
    if port < 0 or port > 65535:
        raise ValueError(f"{field_name} port must be between 0 and 65535: {port}")
    return f"tcp://{host}:{port}"


def configure_ipv6(dist_init_addr):
    addr = dist_init_addr
    end = addr.find("]")
    if end == -1:
        raise ValueError("invalid IPv6 address format: missing ']'")

    host = addr[: end + 1]

    # this only validates the address without brackets: we still need the below checks.

View on GitHub (pinned to 0132848349)

Solutions

  1. Choose a port in 0–65535 (unprivileged ports 1024–65535 for non-root)
  2. If deriving ports arithmetically, clamp or wrap into the valid range
  3. Fix the typo in the configured port number

Example fix

# before
endpoint = "0.0.0.0:70000"
# after
endpoint = "0.0.0.0:7000"
Defensive patterns

Strategy: validation

Validate before calling

assert 0 <= int(port_str) <= 65535, "port out of range"

Prevention

When it happens

Trigger: Passing "host:70000" or "host:-1" to parse_tcp_host_port — int() succeeds but the range check fails.

Common situations: Port computed from a base + offset overflowing past 65535; typo adding an extra digit; using a process id or other large number as a port.

Related errors

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/3d64c2937113e5f9. Report an issue: GitHub.