{"record":{"id":"43664f8125f57453","repo":"sgl-project/sglang","slug":"name-port-port-is-unavailable-and-strict-por","errorCode":null,"errorMessage":"{name} port {port} is unavailable and --strict-ports is enabled. Either use a different port or disable --strict-ports.","messagePattern":"(.+?) port (.+?) is unavailable and --strict-ports is enabled\\. Either use a different port or disable --strict-ports\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/sglang/multimodal_gen/runtime/server_args/server_args.py","lineNumber":1201,"sourceCode":"\n        # BCG captures every graph during a synthetic warmup forward at startup\n        # so serving never records a fresh graph.\n        if self.enable_breakable_cuda_graph and self.disagg_role == RoleType.MONOLITHIC:\n            self.warmup_mode = \"server\"\n\n        # Disaggregated roles do not host the HTTP startup request. Preserve\n        # warmup intent, but schedule it on the first request instead.\n        if self.disagg_role != RoleType.MONOLITHIC and self.warmup_mode == \"server\":\n            self.warmup_mode = \"request\"\n\n        if self.warmup_mode is None:\n            self.warmup_mode = \"off\"\n\n    @staticmethod\n    def _require_port(port: int, name: str) -> None:\n        \"\"\"Raise if *port* is occupied (used under ``--strict-ports``).\"\"\"\n        if not is_port_available(port):\n            raise RuntimeError(\n                f\"{name} port {port} is unavailable and --strict-ports is enabled. \"\n                f\"Either use a different port or disable --strict-ports.\"\n            )\n\n    def _adjust_network_ports(self):\n        # Disagg role instances (encoder/denoiser/decoder) don't serve HTTP,\n        # so skip settling the HTTP port to avoid unnecessary port collisions.\n        needs_http = self.disagg_role in (\n            RoleType.MONOLITHIC,\n            RoleType.SERVER,\n        )\n\n        if self.strict_ports:\n            requested_ports = []\n            if needs_http:\n                requested_ports.append((self.port, \"HTTP\"))\n            for replica in range(self.dp_size or 1):\n                requested_ports.append(","sourceCodeStart":1183,"sourceCodeEnd":1219,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/server_args/server_args.py#L1183-L1219","documentation":"Under --strict-ports, the server probes each requested port and fails fast if one is already bound (is_port_available returns False). This is a RuntimeError raised during network-port adjustment, before server start.","triggerScenarios":"Starting a second instance while the first still holds the port; a crashed process leaving a socket in TIME_WAIT; container port already allocated; --port/--master-port colliding with another service.","commonSituations":"Dev loops restarting the server while the old one is shutting down; CI runners with occupied ports; port-forwarding setups where the host port is taken.","solutions":["Free the port: stop the old process (lsof -i :PORT / kill) or wait for socket release","Choose different ports (--port, --master-port, etc.)","Drop --strict-ports to let the server pick/ignore availability (only if acceptable)"],"exampleFix":"# before\npython -m ... --port 30000 --strict-ports  # port 30000 busy\n# after\npython -m ... --port 30001 --strict-ports","handlingStrategy":"fallback","validationCode":"import socket\n\ndef port_free(port: int) -> bool:\n    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:\n        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)\n        return s.connect_ex(('127.0.0.1', port)) != 0","typeGuard":null,"tryCatchPattern":"try:\n    args.resolve()  # or ServerArgs construction\nexcept RuntimeError as e:\n    if 'unavailable and --strict-ports' in str(e):\n        args.port += 1  # retry with next port\n    else:\n        raise","preventionTips":["Pre-probe ports in launch scripts","Randomize/offset base ports per instance","Grace-period before restarting servers"],"tags":["network","ports","startup","config"],"backgroundTag":"port-already-in-use","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}