sgl-project/sglang · error · ValueError

invalid port in IPv6 address: '{port_str}'

Error message

invalid port in IPv6 address: '{port_str}'

What it means

Thrown by configure_ipv6 when int(port_str) fails, i.e. the text after ':' following the bracketed IPv6 address is not a valid integer port.

Source

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

    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
        except socket.error:
            return False
        except OverflowError:
            return False


def get_zmq_socket(

View on GitHub (pinned to 0132848349)

Solutions

  1. Use a plain integer port: "[fe80::1]:29500"
  2. Check for letter/digit typos (O vs 0, l vs 1) in the port

Example fix

# before
addr = "[fe80::1]:295OO"
# after
addr = "[fe80::1]:29500"
Defensive patterns

Strategy: validation

Validate before calling

port = addr[addr.index("]") + 2:]
assert port.isdigit(), f"non-numeric port {port!r}"

Prevention

When it happens

Trigger: Passing "[fe80::1]:http" or "[fe80::1]:295OO" (letter O instead of zero) as dist_init_addr.

Common situations: Service name instead of numeric port; OCR/typo characters in the port; trailing whitespace or units.

Related errors

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