sgl-project/sglang · error · ValueError

Expected an index file or a single safetensors shard in {mod

Error message

Expected an index file or a single safetensors shard in {model_dir}, found {len(safetensors_files)} shard(s).

What it means

When no index file (model.safetensors.index.json etc.) is present, the loader requires exactly one .safetensors shard in the directory so it can infer a single-file weight map; any other shard count (0 or >1) is rejected.

Source

Thrown at python/sglang/multimodal_gen/tools/build_modelopt_fp8_transformer.py:259

        if filename.endswith(".safetensors.index.json")
    )
    return matches[0] if matches else None


def _load_weight_map(model_dir: str) -> tuple[dict[str, str], str | None]:
    index_filename = _find_index_file(model_dir)
    if index_filename is not None:
        with open(os.path.join(model_dir, index_filename), encoding="utf-8") as f:
            index_data = json.load(f)
        return dict(index_data["weight_map"]), index_filename

    safetensors_files = sorted(
        filename
        for filename in os.listdir(model_dir)
        if filename.endswith(".safetensors")
    )
    if len(safetensors_files) != 1:
        raise ValueError(
            f"Expected an index file or a single safetensors shard in {model_dir}, "
            f"found {len(safetensors_files)} shard(s)."
        )

    shard_name = safetensors_files[0]
    with safe_open(
        os.path.join(model_dir, shard_name), framework="pt", device="cpu"
    ) as f:
        weight_map = {key: shard_name for key in f.keys()}
    index_filename = f"{Path(shard_name).stem}.safetensors.index.json"
    return weight_map, index_filename


def _load_config(model_dir: str) -> dict:
    config_path = os.path.join(model_dir, "config.json")
    with open(config_path, encoding="utf-8") as f:
        return json.load(f)

View on GitHub (pinned to 0132848349)

Solutions

1. Check for a model.safetensors.index.json (verify exact spelling) in the directory
2. If genuinely single-shard, remove extraneous .safetensors files
3. Re-download the export so shards and index are consistent

import os
st = sorted(f for f in os.listdir(model_dir) if f.endswith(".safetensors"))
has_index = any(os.path.isfile(os.path.join(model_dir, n)) for n in ("model.safetensors.index.json",))
assert has_index or len(st) == 1, f"{len(st)} shards, no index"

try:
    wm = _load_weight_map(model_dir)
except ValueError as e:
    logger.error("%s", e)
    raise

When it happens

Trigger: A directory with multiple shards but a missing/misnamed index file, or a directory with zero safetensors files.

Common situations: Index file deleted or named unusually during upload/download; partially downloaded export; user pointed at the wrong directory level.

Related errors

• Could not resolve a transformer directory from: {path}
• Could not resolve backbone.pt from: {path}
• Only per-tensor FP8 scales are supported for diffusion check
• Expected a flat quantization_config dict in the ModelOpt exp
• This tool only supports ModelOpt diffusers FP8 exports (quan

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