sgl-project/sglang · error · ValueError

invalid IPv6 address format: missing ']'

Error message

invalid IPv6 address format: missing ']'

What it means

Thrown by configure_ipv6 when the dist_init_addr contains no ']' character, meaning an IPv6 address was expected in bracketed form [ipv6]:port but the closing bracket is missing.

Source

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

    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.
    # 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)"

View on GitHub (pinned to 0132848349)

Solutions

1. Wrap the IPv6 address in square brackets with a port: "[fe80::1]:29500"
2. If the address is actually IPv4/hostname, use plain host:port form
3. Verify what the scheduler/k8s injected as the init address

Example fix

# before
--dist-init-addr fe80::1:29500
# after
--dist-init-addr [fe80::1]:29500

def is_bracketed_ipv6(addr: str) -> bool:
    return addr.startswith("[") and "]" in addr

When it happens

Trigger: Passing a bare IPv6 address like "fe80::1:29500" or "::1" (no brackets) as dist-init address to configure_ipv6.

Common situations: Forgetting brackets when switching a distributed init method from IPv4 to IPv6; some orchestrators emit unbracketed IPv6 pod addresses.

Related errors

• invalid IPv6 address: {host}
• received IPv6 address format: expected ':' after ']'
• a port must be specified in IPv6 address (format: [ipv6]:por
• invalid port in IPv6 address: '{port_str}'
• media URL timeout must be positive

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