sgl-project/sglang · error · OSError

Could not bind port {port} on any configured address family

Error message

Could not bind port {port} on any configured address family

What it means

try_bind_socket iterates getaddrinfo results for the host/port and attempts bind (plus optional listen) on each; if every candidate sockaddr fails with OSError/OverflowError it closes the socket and raises OSError. Typical causes: port already in use, privileged port without root, or address-family mismatch (IPv6 disabled but host resolves only to v6).

Source

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

        The bound socket. Caller is responsible for closing it.

    Raises:
        OSError: If bind fails on all configured address families.
    """
    for family, socktype, proto, _, sockaddr in _get_addrinfos_for_bind(host, port):
        sock = socket.socket(family, socktype, proto)
        try:
            if family == socket.AF_INET6:
                sock.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 1)
            if reuse_addr:
                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
            sock.bind(sockaddr)
            if listen:
                sock.listen(1)
            return sock
        except (OSError, OverflowError):
            sock.close()
    raise OSError(f"Could not bind port {port} on any configured address family")


def is_port_available(port):
    """Return whether a port is available on all configured address families."""
    try:
        for family, socktype, proto, _, sockaddr in _get_addrinfos_for_bind(port=port):
            sock = socket.socket(family, socktype, proto)
            try:
                if family == socket.AF_INET6:
                    sock.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 1)
                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
                sock.bind(sockaddr)
            finally:
                sock.close()
        return True
    except (OSError, OverflowError):
        return False

View on GitHub (pinned to 0132848349)

Solutions

Free the port (lsof -i :PORT / kill) or pick an ephemeral port (port=0).
For privileged ports, run with privileges/capabilities or choose >1024.
If binding a specific host, confirm it resolves to a family the machine supports.

Example fix

# before
sock = try_bind_socket(host="::", port=80)

# after
sock = try_bind_socket(host="0.0.0.0", port=8080)

Defensive patterns

Strategy: validation

Validate before calling

from sglang.srt.utils.network import is_port_available
if not is_port_available(port):
    port = get_open_port()  # or fail with a clear message

Try / catch

try:
    sock = try_bind_socket(host, port, listen=False)
except OSError:
    port = get_open_port()
    sock = try_bind_socket(host, port, listen=False)

Prevention

Pre-check with is_port_available before binding fixed ports.
Use port=0 for ephemeral allocation in tests.

When it happens

Trigger: get_open_port/get_free_port/bind_port/reserve_port called with a port that is taken, a port <1024 without CAP_NET_BIND_SERVICE, or bind to an address whose family is unavailable.

Common situations: Port collisions in multi-instance test runs; binding 80/4444 without privileges; hosts where ::1 exists but 127.0.0.1 binding of a v6-resolved name fails.

Related errors

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