sgl-project/sglang · error · ValueError

Invalid IPv6 address inside brackets

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.

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')
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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 / catch

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

Prevention

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

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

Appendix: 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)