sgl-project/sglang · error · ValueError

Invalid IPv6 address inside brackets: {host!r}

Error message

Invalid IPv6 address inside brackets: {host!r}

What it means

Raised by NetworkAddress.parse when an address string uses bracket syntax ([host]:port) but the text inside the brackets is not a valid IPv6 address (checked with the ipaddress module). The parser requires bracketed hosts to be IPv6 literals, since brackets exist solely to disambiguate colons in IPv6.

Source

Thrown at python/sglang/srt/utils/network.py:535

            my-hostname:8000    → NetworkAddress("my-hostname", 8000)

        IPv6 addresses **must** be bracketed.  Bare ``::1:8000`` is
        ambiguous and will raise ``ValueError``.

        Raises:
            ValueError: If the string cannot be unambiguously parsed.
        """
        if not addr:
            raise ValueError("Empty address string")

        # --- Bracketed IPv6: [addr]:port ---
        if addr.startswith("["):
            close = addr.find("]")
            if close == -1:
                raise ValueError(f"Missing closing bracket in IPv6 address: {addr!r}")
            host = addr[1:close]
            if not _is_ipv6(host):
                raise ValueError(f"Invalid IPv6 address inside brackets: {host!r}")
            rest = addr[close + 1 :]
            if not rest.startswith(":") or len(rest) < 2:
                raise ValueError(
                    f"Expected ':port' after closing bracket, got: {rest!r}"
                )
            return NetworkAddress(host, _parse_port(rest[1:]))

        # --- Plain host:port (IPv4 / hostname) ---
        if ":" not in addr:
            raise ValueError(f"Missing port in address (expected host:port): {addr!r}")
        host, port_str = addr.rsplit(":", 1)
        if not host:
            raise ValueError(f"Empty host in address: {addr!r}")
        # Guard against bare IPv6 slipping through
        if ":" in host and _is_ipv6(host):
            raise ValueError(
                f"Bare IPv6 address without brackets is ambiguous: {addr!r}. "
                f"Use [{host}]:{port_str} instead."

View on GitHub (pinned to 0132848349)

Solutions

1. Remove the brackets if the host is an IPv4 or hostname: '10.0.0.1:8080'
2. Use a full valid IPv6 literal inside brackets: '[::1]:8080' or '[2001:db8::1]:8080'
3. Abbreviate but keep the IPv6 valid, e.g. '[::]:8080' for all interfaces

Example fix

# before
addr = NetworkAddress.parse('[myhost]:8080')  # ValueError
# after
addr = NetworkAddress.parse('myhost:8080')

import ipaddress
def valid_bracketed_host(addr: str) -> bool:
    if not addr.startswith('['):
        return True
    host = addr[1:addr.find(']')] if ']' in addr else None
    try:
        ipaddress.IPv6Address(host or '')
        return True
    except ipaddress.AddressValueError:
        return False

def is_parseable_address(addr: str) -> bool:
    import ipaddress
    if addr.startswith('['):
        if ']' not in addr:
            return False
        try:
            ipaddress.IPv6Address(addr[1:addr.index(']')])
        except ValueError:
            return False
    return ':' in addr

try:
    addr = NetworkAddress.parse(s)
except ValueError as e:
    logger.warning('bad address %r: %s', s, e); raise ConfigError(s) from e

When it happens

Trigger: Calling NetworkAddress.parse('[not-an-ipv6]:8080'), passing an IPv4 like '[127.0.0.1]:8080', or a hostname in brackets like '[myhost]:9000'.

Common situations: Constructing worker/zookeeper/NCCL addresses from config strings where a user wrapped a plain hostname or IPv4 in brackets, misunderstanding that brackets are IPv6-only syntax.

Related errors

• Expected ':port' after closing bracket, got: {rest!r}
• Bare IPv6 address without brackets is ambiguous: {addr!r}. U
• Missing port in address (expected host:port): {addr!r}
• Empty host in address: {addr!r}
• invalid IPv6 address format: missing ']'

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