sgl-project/sglang · error · ValueError

No valid GPU mappings found in JSON

Error message

No valid GPU mappings found in JSON

What it means

The parsed mapping dict passed key/value validation but normalized to an empty dict — i.e. the JSON object contained no entries ({}), so there are no GPU->IB-device pairs to use. parse_ib_device_config raises ValueError('No valid GPU mappings found in JSON').

Source

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

            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


def get_ib_devices_for_gpu(ib_device_str: Optional[str], gpu_id: int) -> Optional[str]:
    """
    Parse IB device string and get IB devices for a specific GPU ID.

    Supports all the following formats:
    1. Old format: "ib0, ib1, ib2"
    2. New format: {0: "ib0, ib1", 1: "ib2, ib3", 2: "ib4"}
    3. JSON file: path to a JSON file containing the mapping

    Args:
        ib_device_str: The original IB device string or path to JSON file
        gpu_id: The GPU ID to get devices for

    Returns:

View on GitHub (pinned to 0132848349)

Solutions

1. Populate the mapping with at least one GPU id to IB device pair covering the GPUs in use
2. Or remove the JSON config and pass the plain IB device string / leave unset if defaults suffice

Example fix

# before (gpu_ib_map.json)
{}

# after
{"0": "mlx5_0", "1": "mlx5_1"}

import json

def assert_nonempty_mapping(path: str) -> None:
    m = json.load(open(path))
    assert isinstance(m, dict) and len(m) > 0, "IB mapping must contain at least one entry"

try:
    parse_ib_device_config(cfg)
except ValueError as e:
    if "No valid GPU mappings" in str(e):
        raise ConfigError("IB mapping is empty; populate GPU->device pairs") from e
    raise

When it happens

Trigger: Supplying an empty JSON object '{}' (inline or as file contents) as the IB-device config; since invalid entries raise earlier, this is specifically the zero-entries case.

Common situations: Deploying an empty template mapping file that was never populated.

Related errors

• Failed to parse JSON content from file {normalized_input}
• Invalid JSON mapping: {normalized_input}
• Invalid format: expected a mapping from GPU id to IB device
• Invalid format: keys must be integers (or string representat
• 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/185e75024cf62b53. Report an issue: GitHub.