hiyouga/LlamaFactory · error · ValueError

No checkpoint files found in {hf_model_path}

Error message

No checkpoint files found in {hf_model_path}

What it means

The FSDP2 loader resolves model weights from an index weight_map, pytorch_model.bin, *.safetensors, or *.bin files inside the model directory. If none are present, there is nothing to load into the sharded model and it raises. The directory exists but contains no recognizable checkpoint shards.

Source

Thrown at src/llamafactory/v1/plugins/trainer_plugins/distributed/fsdp2.py:518

        else:
            is_safetensors = False
            index_file = os.path.join(hf_model_path, "pytorch_model.bin.index.json")
            if os.path.exists(index_file):
                with open(index_file) as f:
                    index = json.load(f)
                checkpoint_files = sorted(set(index["weight_map"].values()))
                checkpoint_files = [os.path.join(hf_model_path, f) for f in checkpoint_files]
            elif os.path.exists(os.path.join(hf_model_path, "pytorch_model.bin")):
                checkpoint_files = [os.path.join(hf_model_path, "pytorch_model.bin")]
            else:
                checkpoint_files = sorted(glob.glob(os.path.join(hf_model_path, "*.safetensors")))
                if checkpoint_files:
                    is_safetensors = True
                else:
                    checkpoint_files = sorted(glob.glob(os.path.join(hf_model_path, "*.bin")))

        if not checkpoint_files:
            raise ValueError(f"No checkpoint files found in {hf_model_path}")

        param_map = dict(model.named_parameters())
        conversion_ctx = self._try_build_hf_weight_conversion_context(model)
        total_files = len(checkpoint_files)

        for i, ckpt_file in enumerate(checkpoint_files):
            if self.rank == 0:
                logger.info(f"[{i + 1}/{total_files}] Loading {os.path.basename(ckpt_file)} ...")

            if is_safetensors:
                from safetensors import safe_open

                with safe_open(ckpt_file, framework="pt", device="cpu") as f:
                    for key in sorted(f.keys(), key=sort_key):
                        renamed_key = key
                        source_pattern = None
                        if conversion_ctx is not None:
                            renamed_key, source_pattern = conversion_ctx["rename_source_key"](

View on GitHub (pinned to f28afaf635)

Solutions

1. List the directory and confirm *.safetensors or *.bin files exist at that level
2. Point hf_model_path at the subdirectory that actually contains the shards (e.g. .../transformers/)
3. Re-download the model if the snapshot is incomplete (delete cache entry and retry, check HF_HUB_OFFLINE)

Example fix

# before
hf_model_path = "org/model-root"  # weights in model-root/transformers/

# after
hf_model_path = "org/model-root/transformers"

def has_checkpoint_files(d: str) -> bool:
    import glob, json, os
    if os.path.isfile(os.path.join(d, "model.safetensors.index.json")):
        return True
    return bool(
        os.path.isfile(os.path.join(d, "pytorch_model.bin"))
        or glob.glob(os.path.join(d, "*.safetensors"))
        or glob.glob(os.path.join(d, "*.bin"))
    )

assert has_checkpoint_files(hf_model_path), f"no weight shards in {hf_model_path}"

When it happens

Trigger: hf_model_path points at a directory with config.json/tokenizer but no weight files (e.g. a repo with weights in a subfolder like 'transformers/'), or all files use an unrecognized extension.

Common situations: Pointing at the root of a hub repo whose weights live under a subdirectory; interrupted download that left only metadata files; pointing at a tokenizer-only or config-only directory.

Related errors

• Checkpoint directory does not exist: {ckpt_dir}
• hf_model_path='{hf_model_path}' does not exist locally and h
• Invalid or inaccessible file path.
• The current model does not support `chat`.
• The current model does not support `stream_chat`.

AI-assisted analysis of hiyouga/LlamaFactory@f28afaf635 (2026-08-14). Data as JSON: /api/errors/0d4b9c0ec140af29. Report an issue: GitHub.