sgl-project/sglang · error · ValueError

{field_name} port must be an integer: {port_str}

Error message

{field_name} port must be an integer: {port_str}

What it means

Thrown by parse_tcp_host_port when int(port_str) fails, i.e. the text after the last ':' is not a valid integer (e.g. "host:abc" or "host:55 55").

Source

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

    if addr.startswith("tcp://"):
        addr = addr[len("tcp://") :]

    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 ']'")

View on GitHub (pinned to 0132848349)

Solutions

1. Replace service names with the numeric port (e.g. 80, 5555)
2. Strip any non-digit characters from the port substring
3. Verify the port field in the config is typed as an integer before string formatting

Example fix

# before
endpoint = "localhost:http"
# after
endpoint = "localhost:80"

port_str = endpoint.rsplit(":", 1)[1]
assert port_str.isdigit(), f"port {port_str!r} not an integer"

When it happens

Trigger: Passing "localhost:http" or "1.2.3.4:5555a" to parse_tcp_host_port.

Common situations: Using a service name instead of a numeric port; a stray character or space appended to the port; copy-paste including a footnote marker.

Related errors

• {field_name} port must be between 0 and 65535: {port}
• {field_name} is required
• {field_name} must be formatted as tcp://host:port or host:po
• {field_name} must include both host and port: {value!r}
• a port must be specified in IPv6 address (format: [ipv6]:por

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