sgl-project/sglang · error · ValueError

invalid IPv6 address: {host}

Error message

invalid IPv6 address: {host}

What it means

Thrown by configure_ipv6 when the bracketed host fails the is_valid_ipv6_address check, i.e. the text between '[' and ']' is not a syntactically valid IPv6 address.

Source

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

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

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

View on GitHub (pinned to 0132848349)

Solutions

  1. Use a full valid IPv6 literal, e.g. "[2001:db8::1]:29500"
  2. Remove IPv4 addresses or hostnames from bracketed form
  3. Validate the address with ipaddress.IPv6Address before launching

Example fix

# before
addr = "[192.168.1.5]:29500"
# after
addr = "192.168.1.5:29500"  # or a real IPv6 like [2001:db8::1]:29500
Defensive patterns

Strategy: validation

Validate before calling

import ipaddress
try:
    ipaddress.IPv6Address(addr.strip("[]").rsplit(":", 1)[0] if "]" in addr else None)
    ok = True
except Exception:
    ok = False

Type guard

def valid_ipv6_with_port(addr: str) -> bool:
    try:
        host = addr[1:addr.index("]")]
        ipaddress.IPv6Address(host)
        return addr[addr.index("]") + 1] == ":" and addr[addr.index("]") + 2:].isdigit()
    except (ValueError, IndexError):
        return False

Prevention

When it happens

Trigger: Passing "[not-an-addr]:29500", "[192.168.1.1]:29500" (IPv4 in brackets), or a truncated IPv6 like "[fe80::]:29500" variant that fails validation.

Common situations: Copy-paste truncating the address; interface/zone suffixes or a hostname accidentally placed inside brackets.

Related errors

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