sgl-project/sglang · error · ValueError

{field_name} must be formatted as tcp://host:port or host:po

Error message

{field_name} must be formatted as tcp://host:port or host:port

What it means

Thrown by parse_tcp_host_port when addr.rsplit(":", 1) raises ValueError, i.e. the string contains no ':' at all so it cannot be split into host and port. This is a defensive branch (rsplit on a plain string rarely raises) covering malformed input lacking a colon.

Source

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

        if len(parts) != 2:
            raise ValueError
        return int(parts[0]), int(parts[1])
    except ValueError:
        return None, None


def parse_tcp_host_port(value: str | None, field_name: str) -> tuple[str, int]:
    if value is None or not str(value).strip():
        raise ValueError(f"{field_name} is required")

    addr = str(value).strip()
    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

View on GitHub (pinned to 0132848349)

Solutions

1. Include the port: use host:port or tcp://host:port format
2. If you meant to use a default port, append it explicitly to the configured value

Example fix

# before
endpoint = "localhost"
# after
endpoint = "localhost:5555"

assert ":" in endpoint, f"endpoint {endpoint!r} must be host:port"

def looks_like_host_port(v: str) -> bool:
    v = v.removeprefix("tcp://")
    return ":" in v

When it happens

Trigger: Passing a colon-less string like "localhost" or "myhost" to parse_tcp_host_port after the tcp:// prefix is stripped.

Common situations: User supplies only a hostname or only a port in an endpoint config; a template renders an incomplete endpoint string.

Related errors

• {field_name} is required
• {field_name} must include both host and port: {value!r}
• {field_name} port must be an integer: {port_str}
• {field_name} port must be between 0 and 65535: {port}
• Unsupported socket type: {socket_type}

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