sgl-project/sglang · error · RuntimeError

File {normalized_input} does not exist.

Error message

File {normalized_input} does not exist.

What it means

While parsing the mooncake transfer engine's --mooncake-ip-device configuration, a string ending in .json was treated as a path to a GPU-id-to-IB-device mapping file, but os.path.isfile reported the file does not exist. The parse_ib_device_config helper raises before attempting to open it. Callers are get_ib_devices_for_gpu and _validate_ib_devices during MooncakeTransferEngine construction.

Source

Thrown at python/sglang/srt/distributed/device_communicators/mooncake_transfer_engine.py:38

# Module-level shared engine instance, set by init_mooncake_transfer_engine().
_mooncake_transfer_engine: Optional[MooncakeTransferEngine] = None


def parse_ib_device_config(
    ib_device_str: Optional[str],
) -> Optional[Union[str, Dict[int, str]]]:
    """Parse IB device config from a shared string, JSON mapping, or JSON file."""
    if ib_device_str is None or not ib_device_str.strip():
        return None

    normalized_input = ib_device_str.strip()
    if not normalized_input.endswith(".json") and not normalized_input.startswith("{"):
        return normalized_input

    if normalized_input.endswith(".json"):
        if not os.path.isfile(normalized_input):
            raise RuntimeError(f"File {normalized_input} does not exist.")
        try:
            with open(normalized_input, "r", encoding="utf-8") as file:
                mapping = json.load(file)
        except json.JSONDecodeError as exc:
            raise RuntimeError(
                f"Failed to parse JSON content from file {normalized_input}"
            ) from exc
        except (IOError, OSError) as exc:
            raise RuntimeError(
                f"Failed to read JSON file {normalized_input}: {exc}"
            ) from exc
    else:
        try:
            mapping = json.loads(normalized_input)
        except json.JSONDecodeError as exc:
            raise ValueError(f"Invalid JSON mapping: {normalized_input}") from exc

    if not isinstance(mapping, dict):

View on GitHub (pinned to 0132848349)

Solutions

  1. Check the path exists on every node that constructs the transfer engine (ls <path> on that host)
  2. Use an absolute path for the .json mapping file in launch scripts / cluster configs
  3. If you meant to pass an inline mapping, remove the .json suffix and pass the JSON object string directly, or pass a plain comma-separated IB device string

Example fix

# before
--mooncake-ip-device /wrong/path/gpu_ib_map.json

# after
--mooncake-ip-device /etc/sglang/gpu_ib_map.json  # absolute, present on all nodes
Defensive patterns

Strategy: validation

Validate before calling

import os

def check_ib_config_path(cfg: str) -> None:
    if cfg.strip().endswith(".json") and not os.path.isfile(cfg.strip()):
        raise FileNotFoundError(f"IB mapping file not found: {cfg}"); resolve to absolute paths early

Try / catch

try:
    get_ib_devices_for_gpu(cfg, gpu_id)
except (RuntimeError, ValueError) as e:
    raise ConfigurationError(f"bad mooncake IB config: {e}") from e

Prevention

When it happens

Trigger: Passing a *.json path via the mooncake IB-device config string (file or CLI arg) where the path is wrong, relative to a different working directory, or on a node where the file was not provisioned.

Common situations: Typos or stale paths in the config file argument, relative paths resolved from a different CWD in multi-node launches, or the JSON mapping file present on the head node but missing on worker nodes.

Related errors

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