sgl-project/sglang · error · RuntimeError

No free port available.

Error message

No free port available.

What it means

reserve_port tried every candidate port in the range and none could be bound — all occupied or otherwise bind-failed, so it gives up rather than return a port that isn't actually reserved.

Source

Thrown at python/sglang/utils.py:463

process_socket_map = weakref.WeakKeyDictionary()


def reserve_port(host, start=30000, end=40000):
    """
    Reserve an available port by trying to bind a socket.
    Returns a tuple (port, lock_socket) where `lock_socket` is kept open to hold the lock.
    """
    from sglang.srt.utils.network import try_bind_socket

    candidates = list(range(start, end))
    random.shuffle(candidates)
    for port in candidates:
        try:
            sock = try_bind_socket(host, port)
            return port, sock
        except OSError:
            continue
    raise RuntimeError("No free port available.")


def release_port(lock_socket):
    """
    Release the reserved port by closing the lock socket.
    """
    try:
        lock_socket.close()
    except Exception as e:
        print(f"Error closing socket: {e}")


def execute_shell_command(command: str) -> subprocess.Popen:
    """
    Execute a shell command and return its process handle.
    Supports leading KEY=VALUE env vars (e.g. "VAR=1 python script.py") so that
    notebook/CI commands work without requiring shell=True.
    """

View on GitHub (pinned to 0132848349)

Solutions

1. Widen or change the port range passed to reserve_port
2. Reduce concurrent test parallelism
3. Free leaked listening sockets from prior runs

Example fix

# before
port, sock = reserve_port(host)
# after
port, sock = reserve_port(host, min_port=30000, max_port=40000)

try:
    port, sock = reserve_port(host)
except RuntimeError:
    port, sock = reserve_port(host, min_port=other_range_start)

When it happens

Trigger: launch_server_cmd in a test environment where all ports in the scan range are held (heavily parallel test runs, small port exhaustion, or privileged ports excluded).

Common situations: CI running many sglang server tests concurrently; low ip_local_port_range or narrow allowed range.

Related errors

• a port must be specified in IPv6 address (format: [ipv6]:por
• {port_name} has invalid port number {port}. Valid TCP port r
• {port_name} at {port} is not available in {timeout_s} second
• Port out of range (0-65535): {port}
• Expected ':port' after closing bracket, got: {rest!r}

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