sgl-project/sglang · error · ValueError

Invalid format: expected a mapping from GPU id to IB device

Error message

Invalid format: expected a mapping from GPU id to IB device string

What it means

The parsed mooncake IB-device config (from file or inline JSON) is valid JSON but not a JSON object — e.g. an array or a scalar string. parse_ib_device_config requires a dict mapping GPU id to IB device string before it iterates keys/values.

Source

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

        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):
        raise ValueError(
            "Invalid format: expected a mapping from GPU id to IB device string"
        )

    normalized_mapping: Dict[int, str] = {}
    for gpu_key, ib_devices in mapping.items():
        normalized_key = int(gpu_key) if str(gpu_key).isdigit() else None
        if normalized_key is None or not isinstance(ib_devices, str):
            raise ValueError(
                "Invalid format: keys must be integers (or string "
                "representations of integers) and values must be strings"
            )
        normalized_mapping[normalized_key] = ib_devices.strip()

    if not normalized_mapping:
        raise ValueError("No valid GPU mappings found in JSON")

    return normalized_mapping

View on GitHub (pinned to 0132848349)

Solutions

1. Change the value to a JSON object keyed by GPU id: {"0": "mlx5_0", "1": "mlx5_1"}
2. If all GPUs share one device, drop the JSON and pass the plain device string

Example fix

# before
--mooncake-ip-device '["mlx5_0", "mlx5_1"]'

# after
--mooncake-ip-device '{"0": "mlx5_0", "1": "mlx5_1"}'

import json

def is_ib_mapping(v) -> bool:
    return isinstance(v, dict) and all(
        str(k).isdigit() and isinstance(x, str) and x.strip()
        for k, x in v.items()
    )

def is_ib_device_mapping(cfg: object) -> bool:
    return (
        isinstance(cfg, str)
        or (isinstance(cfg, dict) and bool(cfg)
            and all(str(k).isdigit() and isinstance(v, str) for k, v in cfg.items()))
    )

if not is_ib_mapping(json.loads(cfg)):
    raise ConfigError("expected a GPU-id -> IB-device-string object")
parse_ib_device_config(cfg)

When it happens

Trigger: Supplying a JSON array like ["mlx5_0", "mlx5_1"] or a bare string "\"mlx5_0\"" as the mapping; note a bare non-JSON string input returns earlier, so this specifically comes from JSON-parsed values that are not dicts.

Common situations: Assuming the config takes a list of devices indexed by GPU order instead of an explicit id->device mapping.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Invalid format: keys must be integers (or string representat
• Failed to parse JSON content from file {normalized_input}
• Invalid JSON mapping: {normalized_input}
• No valid GPU mappings found in JSON
• Failed to load config from {file_path}: {str(e)}

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