{"record":{"id":"63ac528aff7b68a5","repo":"sgl-project/sglang","slug":"port-name-has-invalid-port-number-port-valid","errorCode":null,"errorMessage":"{port_name} has invalid port number {port}. Valid TCP port range is 0-{MAX_VALID_PORT}.","messagePattern":"(.+?) has invalid port number (.+?)\\. Valid TCP port range is 0-(.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/utils/network.py","lineNumber":69,"sourceCode":"\n\nMAX_VALID_PORT = 65535\n\n\ndef wait_port_available(\n    port: int,\n    port_name: str,\n    timeout_s: Optional[int] = None,\n    raise_exception: bool = True,\n) -> bool:\n    if timeout_s is None:\n        # A killed server can hold its ports well past kill_process_tree()'s\n        # return while GPU teardown completes (>30s observed on GB300), so CI\n        # raises this via SGLANG_WAIT_PORT_TIMEOUT before relaunching a server\n        # on the same port plan.\n        timeout_s = int(os.environ.get(\"SGLANG_WAIT_PORT_TIMEOUT\", \"30\"))\n    if port < 0 or port > MAX_VALID_PORT:\n        raise ValueError(\n            f\"{port_name} has invalid port number {port}. \"\n            f\"Valid TCP port range is 0-{MAX_VALID_PORT}.\"\n        )\n\n    error_message = f\"{port_name} at {port} is not available\"\n    for i in range(timeout_s):\n        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=}\"","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/utils/network.py#L51-L87","documentation":"wait_port_available validates the port argument before its wait loop; anything outside 0-65535 raises immediately with the offending value. This is a caller bug (bad port arithmetic, unset env var parsed as -1, or a port literal typos like 70000) rather than a network condition.","triggerScenarios":"init_new passing a derived port (base_port + dp_rank*size etc.) that overflowed 65535 or went negative, or a port string parsed incorrectly from an environment variable.","commonSituations":"Large --port plus --dp-size/--tp-size offsets exceeding 65535; port defaults of -1 used as 'unset' sentinel reaching this function; misparsed SGLANG_PORT env vars.","solutions":["Fix the port computation so it stays within 0-65535 (clamp or reduce the base port).","Check env vars feeding the port for garbage values (e.g., print/validate before launch).","Use get_open_port() to allocate ephemeral ports instead of arithmetic on a fixed base."],"exampleFix":"# before\nport = args.port + rank * 1000  # overflows for large rank/port\n\n# after\nport = args.port + rank * 1000\nassert 0 <= port <= 65535, f\"port {port} out of range\"","handlingStrategy":"validation","validationCode":"assert isinstance(port, int) and 0 <= port <= 65535, f\"bad port {port!r}\"","typeGuard":"def is_valid_port(p) -> bool:\n    return isinstance(p, int) and 0 <= p <= 65535","tryCatchPattern":null,"preventionTips":["Validate derived ports (base + offsets) before launch.","Use get_open_port() instead of arithmetic."],"tags":["network","port","validation"],"backgroundTag":"port-out-of-range","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}