What causes "Cannot resolve host {host!r}: {e}" in sgl-project/sglang?

Fix the hostname or add it to /etc/hosts/DNS.

sgl-project/sglang · error · ValueError

Cannot resolve host {host!r}: {e}

Error message

Cannot resolve host {host!r}: {e}

What it means

NetworkAddress.resolve_host DNS-resolves the host via getaddrinfo with AI_ADDRCONFIG; a gaierror (name or service not known, temporary DNS failure) is wrapped in ValueError naming the host. Used before NCCL remote-group setup and by resolved().

Source

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

    def to_host_port_str(self) -> str:
        """``host:port`` string for gRPC listen address, session IDs, logs."""
        return f"{_wrap(self.host)}:{self.port}"

    @staticmethod
    def resolve_host(host: str) -> str:
        """Return *host* as-is if it's an IP, otherwise DNS-resolve to one."""
        try:
            ipaddress.ip_address(host)
            return host
        except ValueError:
            pass
        try:
            return socket.getaddrinfo(
                host, None, socket.AF_UNSPEC, 0, 0, socket.AI_ADDRCONFIG
            )[0][4][0]
        except socket.gaierror as e:
            raise ValueError(f"Cannot resolve host {host!r}: {e}") from e

    def resolved(self) -> NetworkAddress:
        """DNS-resolve hostname to IP; return self if already an IP."""
        ip = self.resolve_host(self.host)
        return self if ip == self.host else NetworkAddress(ip, self.port)

    def to_bind_tuple(self) -> Tuple[str, int]:
        """Raw ``(host, port)`` tuple for ``socket.bind()`` / ``socket.connect()``.

        Returns the *unwrapped* host — sockets need the raw address, not
        the bracketed form.
        """
        return (self.host, self.port)

    @staticmethod
    def parse(addr: str) -> NetworkAddress:
        """Parse a ``host:port`` string into a ``NetworkAddress``.

View on GitHub (pinned to 0132848349)

Solutions

Fix the hostname or add it to /etc/hosts/DNS.
Verify with `getent hosts <name>` or `python -c "import socket; print(socket.getaddrinfo('<name>', None))"`.
For multi-node, wait until all node DNS entries/services are up before launching.

Example fix

# before
addr = NetworkAddress.parse("node-01x:8000")  # typo

# after
addr = NetworkAddress.parse("node-001:8000")

Defensive patterns

Strategy: validation

Validate before calling

import socket
try:
    socket.getaddrinfo(host, None)
except socket.gaierror:
    raise SystemExit(f"host {host} not resolvable; fix DNS//etc/hosts")

Try / catch

try:
    ip = NetworkAddress(host, port).resolved()
except ValueError as e:
    # retry once after short delay for transient DNS, then fail
    ...

Prevention

Resolve all node hostnames during preflight before launching multi-node jobs.
Use IPs or maintain accurate /etc/hosts in static clusters.

When it happens

Trigger: Passing a hostname that doesn't exist (typo in --nnodes host list, stale /etc/hosts entry) or a DNS outage when resolve_host()/resolved() is called.

Common situations: Multi-node launches with misspelled node names; Kubernetes headless service names not yet resolvable; VPN/DNS interruption during engine startup.

Related errors

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