{"record":{"id":"d1927f0561f12f94","repo":"sgl-project/sglang","slug":"port-name-at-port-is-not-available-in-timeout","errorCode":null,"errorMessage":"{port_name} at {port} is not available in {timeout_s} seconds. {error_message}","messagePattern":"(.+?) at (.+?) is not available in (.+?) seconds\\. (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/utils/network.py","lineNumber":94,"sourceCode":"        if is_port_available(port):\n            return True\n\n        if i > 10 and i % 5 == 0:\n            process = find_process_using_port(port)\n            if process is None:\n                logger.warning(\n                    f\"The port {port} is in use, but we could not find the process that uses it.\"\n                )\n            else:\n                pid = process.pid\n                error_message = f\"{port_name} is used by a process already. {process.name()=}' {process.cmdline()=} {process.status()=} {pid=}\"\n                logger.info(\n                    f\"port {port} is in use. Waiting for {i} seconds for {port_name} to be available. {error_message}\"\n                )\n        time.sleep(1)\n\n    if raise_exception:\n        raise ValueError(\n            f\"{port_name} at {port} is not available in {timeout_s} seconds. {error_message}\"\n        )\n    return False\n\n\ndef _get_addrinfos_for_bind(host=None, port=0):\n    \"\"\"Return deduplicated addrinfo tuples for binding (one per address family).\n\n    Args:\n        host: Bind address. None (with AI_PASSIVE) resolves to wildcard\n              addresses (0.0.0.0 / ::) suitable for accepting on all interfaces.\n        port: Port number. 0 lets the OS assign an available ephemeral port.\n\n    Flags:\n        AI_ADDRCONFIG — only return families actually configured on this host.\n        AI_PASSIVE    — return wildcard addresses suitable for bind().\n\n    Falls back to AF_INET if getaddrinfo fails (e.g. DNS misconfiguration).","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/utils/network.py#L76-L112","documentation":"wait_port_available polls a port once per second for timeout_s (default 30, overridable via SGLANG_WAIT_PORT_TIMEOUT) and raises if it never becomes bindable. Usually the previous server process is still holding the port — the comment notes GPU teardown can keep ports held >30s on GB300-class hardware.","triggerScenarios":"init_new relaunching a server on the same port plan while the old process's sockets are still in TIME_WAIT/held during GPU teardown; or another service occupying the port.","commonSituations":"CI restarting servers quickly; kill_process_tree returning before the OS releases ports; port collisions between sglang instances or with other services.","solutions":["Raise the budget: export SGLANG_WAIT_PORT_TIMEOUT=120.","Ensure the old process fully exits before relaunch (wait on PID, check nvidia-smi for leftover CUDA contexts).","Use a different port / let sglang pick a free port via get_open_port."],"exampleFix":"# before\nkill_process_tree(old_pid); relaunch(port=30000)\n\n# after\nkill_process_tree(old_pid)\nimport os; os.environ[\"SGLANG_WAIT_PORT_TIMEOUT\"] = \"120\"\nrelaunch(port=30000)","handlingStrategy":"retry","validationCode":"import socket\n\ndef port_free(port: int) -> bool:\n    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:\n        return s.connect_ex((\"127.0.0.1\", port)) != 0","typeGuard":null,"tryCatchPattern":"for attempt in range(3):\n    try:\n        wait_port_available(port, raise_exception=True)\n        break\n    except ValueError:\n        time.sleep(10)\nelse:\n    raise","preventionTips":["Set SGLANG_WAIT_PORT_TIMEOUT higher in CI.","Wait for the old server process (and its GPU teardown) to fully exit before relaunch."],"tags":["network","port","timeout","ci"],"backgroundTag":"address-in-use","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}