{"record":{"id":"3301d909750b523c","repo":"sgl-project/sglang","slug":"no-free-port-available","errorCode":null,"errorMessage":"No free port available.","messagePattern":"No free port available\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/utils.py","lineNumber":463,"sourceCode":"process_socket_map = weakref.WeakKeyDictionary()\n\n\ndef reserve_port(host, start=30000, end=40000):\n    \"\"\"\n    Reserve an available port by trying to bind a socket.\n    Returns a tuple (port, lock_socket) where `lock_socket` is kept open to hold the lock.\n    \"\"\"\n    from sglang.srt.utils.network import try_bind_socket\n\n    candidates = list(range(start, end))\n    random.shuffle(candidates)\n    for port in candidates:\n        try:\n            sock = try_bind_socket(host, port)\n            return port, sock\n        except OSError:\n            continue\n    raise RuntimeError(\"No free port available.\")\n\n\ndef release_port(lock_socket):\n    \"\"\"\n    Release the reserved port by closing the lock socket.\n    \"\"\"\n    try:\n        lock_socket.close()\n    except Exception as e:\n        print(f\"Error closing socket: {e}\")\n\n\ndef execute_shell_command(command: str) -> subprocess.Popen:\n    \"\"\"\n    Execute a shell command and return its process handle.\n    Supports leading KEY=VALUE env vars (e.g. \"VAR=1 python script.py\") so that\n    notebook/CI commands work without requiring shell=True.\n    \"\"\"","sourceCodeStart":445,"sourceCodeEnd":481,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/utils.py#L445-L481","documentation":"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.","triggerScenarios":"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).","commonSituations":"CI running many sglang server tests concurrently; low ip_local_port_range or narrow allowed range.","solutions":["Widen or change the port range passed to reserve_port","Reduce concurrent test parallelism","Free leaked listening sockets from prior runs"],"exampleFix":"# before\nport, sock = reserve_port(host)\n# after\nport, sock = reserve_port(host, min_port=30000, max_port=40000)","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    port, sock = reserve_port(host)\nexcept RuntimeError:\n    port, sock = reserve_port(host, min_port=other_range_start)","preventionTips":["Use a wide, high port range in tests","Limit test parallelism to avoid port exhaustion"],"tags":["network","port","test-infra"],"backgroundTag":"no-free-port-available","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}