{"record":{"id":"6c7b57e92e6a0623","repo":"sgl-project/sglang","slug":"expected-an-index-file-or-a-single-safetensors-sha","errorCode":null,"errorMessage":"Expected an index file or a single safetensors shard in {model_dir}, found {len(safetensors_files)} shard(s).","messagePattern":"Expected an index file or a single safetensors shard in (.+?), found (.+?) shard\\(s\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/tools/build_modelopt_fp8_transformer.py","lineNumber":259,"sourceCode":"        if filename.endswith(\".safetensors.index.json\")\n    )\n    return matches[0] if matches else None\n\n\ndef _load_weight_map(model_dir: str) -> tuple[dict[str, str], str | None]:\n    index_filename = _find_index_file(model_dir)\n    if index_filename is not None:\n        with open(os.path.join(model_dir, index_filename), encoding=\"utf-8\") as f:\n            index_data = json.load(f)\n        return dict(index_data[\"weight_map\"]), index_filename\n\n    safetensors_files = sorted(\n        filename\n        for filename in os.listdir(model_dir)\n        if filename.endswith(\".safetensors\")\n    )\n    if len(safetensors_files) != 1:\n        raise ValueError(\n            f\"Expected an index file or a single safetensors shard in {model_dir}, \"\n            f\"found {len(safetensors_files)} shard(s).\"\n        )\n\n    shard_name = safetensors_files[0]\n    with safe_open(\n        os.path.join(model_dir, shard_name), framework=\"pt\", device=\"cpu\"\n    ) as f:\n        weight_map = {key: shard_name for key in f.keys()}\n    index_filename = f\"{Path(shard_name).stem}.safetensors.index.json\"\n    return weight_map, index_filename\n\n\ndef _load_config(model_dir: str) -> dict:\n    config_path = os.path.join(model_dir, \"config.json\")\n    with open(config_path, encoding=\"utf-8\") as f:\n        return json.load(f)\n","sourceCodeStart":241,"sourceCodeEnd":277,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/tools/build_modelopt_fp8_transformer.py#L241-L277","documentation":"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.","triggerScenarios":"A directory with multiple shards but a missing/misnamed index file, or a directory with zero safetensors files.","commonSituations":"Index file deleted or named unusually during upload/download; partially downloaded export; user pointed at the wrong directory level.","solutions":["Check for a model.safetensors.index.json (verify exact spelling) in the directory","If genuinely single-shard, remove extraneous .safetensors files","Re-download the export so shards and index are consistent"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import os\nst = sorted(f for f in os.listdir(model_dir) if f.endswith(\".safetensors\"))\nhas_index = any(os.path.isfile(os.path.join(model_dir, n)) for n in (\"model.safetensors.index.json\",))\nassert has_index or len(st) == 1, f\"{len(st)} shards, no index\"","typeGuard":null,"tryCatchPattern":"try:\n    wm = _load_weight_map(model_dir)\nexcept ValueError as e:\n    logger.error(\"%s\", e)\n    raise","preventionTips":["Never delete or rename index json files when resharing checkpoints","Verify shard/index consistency after downloads"],"tags":["modelopt","fp8","safetensors","weight-map"],"backgroundTag":"missing-index-file","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}