sgl-project/sglang · error · ValueError

a port must be specified in IPv6 address (format: [ipv6]:por

Error message

a port must be specified in IPv6 address (format: [ipv6]:port)

What it means

Thrown by configure_ipv6 when the string ends at ']' or the ':' is present but the port substring is empty — distributed init over IPv6 requires an explicit port.

Source

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

    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.
    # if it's invalid, immediately raise an error so we know it's not formatting issues.
    if not is_valid_ipv6_address(host[1:end]):
        raise ValueError(f"invalid IPv6 address: {host}")

    port_str = None
    if len(addr) > end + 1:
        if addr[end + 1] == ":":
            port_str = addr[end + 2 :]
        else:
            raise ValueError("received IPv6 address format: expected ':' after ']'")

    if not port_str:
        raise ValueError(
            "a port must be specified in IPv6 address (format: [ipv6]:port)"
        )

    try:
        port = int(port_str)
    except ValueError:
        raise ValueError(f"invalid port in IPv6 address: '{port_str}'")
    return port, host


def is_port_available(port):
    """Return whether a port is available."""
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
        try:
            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
            s.bind(("", port))
            s.listen(1)
            return True

View on GitHub (pinned to 0132848349)

Solutions

1. Append an explicit port: "[fe80::1]:29500"
2. Check that the port variable in your launch script/config is set

Example fix

# before
addr = "[fe80::1]:"
# after
addr = "[fe80::1]:29500"

end = addr.index("]")
assert len(addr) > end + 2 and addr[end + 2:].strip(), "port required after [ipv6]:"

When it happens

Trigger: Passing "[fe80::1]" or "[fe80::1]:" as dist_init_addr.

Common situations: Only the address was templated into the config and the port variable was empty; user assumed a default port exists.

Related errors

• invalid IPv6 address format: missing ']'
• invalid IPv6 address: {host}
• received IPv6 address format: expected ':' after ']'
• invalid port in IPv6 address: '{port_str}'
• {port_name} has invalid port number {port}. Valid TCP port r

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