{"record":{"id":"105a9aa19dcc0c64","repo":"sgl-project/sglang","slug":"bare-ipv6-address-without-brackets-is-ambiguous","errorCode":null,"errorMessage":"Bare IPv6 address without brackets is ambiguous: {addr!r}. Use [{host}]:{port_str} instead.","messagePattern":"Bare IPv6 address without brackets is ambiguous: (.+?)\\. Use \\[(.+?)\\]:(.+?) instead\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/utils/network.py","lineNumber":551,"sourceCode":"            host = addr[1:close]\n            if not _is_ipv6(host):\n                raise ValueError(f\"Invalid IPv6 address inside brackets: {host!r}\")\n            rest = addr[close + 1 :]\n            if not rest.startswith(\":\") or len(rest) < 2:\n                raise ValueError(\n                    f\"Expected ':port' after closing bracket, got: {rest!r}\"\n                )\n            return NetworkAddress(host, _parse_port(rest[1:]))\n\n        # --- Plain host:port (IPv4 / hostname) ---\n        if \":\" not in addr:\n            raise ValueError(f\"Missing port in address (expected host:port): {addr!r}\")\n        host, port_str = addr.rsplit(\":\", 1)\n        if not host:\n            raise ValueError(f\"Empty host in address: {addr!r}\")\n        # Guard against bare IPv6 slipping through\n        if \":\" in host and _is_ipv6(host):\n            raise ValueError(\n                f\"Bare IPv6 address without brackets is ambiguous: {addr!r}. \"\n                f\"Use [{host}]:{port_str} instead.\"\n            )\n        return NetworkAddress(host, _parse_port(port_str))\n\n    def __str__(self) -> str:\n        return self.to_host_port_str()\n\n    def __repr__(self) -> str:\n        return f\"NetworkAddress({self.host!r}, {self.port})\"\n\n\ndef resolve_base_url(base_url: str, host: str, port: int) -> str:\n    \"\"\"Base URL a client sends to: ``base_url`` if set, else ``http://host:port``\n    (IPv6-correct via :class:`NetworkAddress`).\"\"\"\n    if base_url:\n        return base_url\n    return NetworkAddress(host, port).to_url()","sourceCodeStart":533,"sourceCodeEnd":569,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/utils/network.py#L533-L569","documentation":"The address contains multiple colons and the pre-split host portion is itself a valid IPv6 literal (e.g. '::1:8080' parses host='::1'). Because 'host:port' splitting is ambiguous for IPv6, the parser requires bracket notation.","triggerScenarios":"NetworkAddress.parse('::1:8080') or '2001:db8::1:8080' — the rsplit leaves an IPv6-looking host with a port appended.","commonSituations":"Users writing IPv6 plus port the natural way without brackets; also NCCL/zookeeper/dist init addresses configured for IPv6 clusters.","solutions":["Wrap the IPv6 part in brackets: '[::1]:8080'","Use the exact form from the error message hint: '[{host}]:{port}'","Audit config templates that interpolate IPv6 hosts to add brackets conditionally"],"exampleFix":"# before\naddr = NetworkAddress.parse('2001:db8::1:8080')\n# after\naddr = NetworkAddress.parse('[2001:db8::1]:8080')","handlingStrategy":"validation","validationCode":"import re\ndef bracket_if_ipv6(addr: str) -> str:\n    if addr.count(':') > 1 and not addr.startswith('['):\n        host, port = addr.rsplit(':', 1)\n        return f'[{host}]:{port}'\n    return addr","typeGuard":"null","tryCatchPattern":"try:\n    NetworkAddress.parse(addr)\nexcept ValueError as e:\n    if 'without brackets' in str(e):\n        host, port = addr.rsplit(':', 1)\n        addr = f'[{host}]:{port}'\n        NetworkAddress.parse(addr)","preventionTips":["Always bracket IPv6 hosts when embedding ports","Wrap config normalization in bracket_if_ipv6","Document the [ipv6]:port convention in cluster setup guides"],"tags":["network","ipv6","address-parsing","sglang"],"backgroundTag":"invalid-host-port-format","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}