hiyouga/LlamaFactory · error · ValueError

hf_model_path='{hf_model_path}' does not exist locally and h

Error message

hf_model_path='{hf_model_path}' does not exist locally and huggingface_hub is not available to download it. Please provide a local model directory or install huggingface_hub. Error: {e}

What it means

When hf_model_path is neither a local directory nor file, the loader treats it as a Hub repo id and needs huggingface_hub.snapshot_download to fetch it. If that import fails, there is no way to obtain the weights and the original ImportError is chained into this ValueError. The suggested remedies (local path or installing huggingface_hub) are embedded in the message.

Source

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

        - If `hf_model_path` is an existing directory, return it.
        - If it's a file path, return its parent directory.
        - Otherwise treat it as a Hugging Face Hub repo id and download/resolve to the local cache dir.
        """
        if not hf_model_path:
            return hf_model_path

        # Local directory or file path.
        if os.path.isdir(hf_model_path):
            return hf_model_path
        if os.path.isfile(hf_model_path):
            return os.path.dirname(hf_model_path)

        # HuggingFace Hub repo id: snapshot to local cache so we can glob/index files.
        try:
            from huggingface_hub import snapshot_download
        except ImportError as e:
            raise ValueError(
                f"hf_model_path='{hf_model_path}' does not exist locally and huggingface_hub is not available "
                f"to download it. Please provide a local model directory or install huggingface_hub. Error: {e}"
            ) from e

        revision = os.getenv("HF_REVISION")
        offline = os.getenv("HF_HUB_OFFLINE") == "1" or os.getenv("TRANSFORMERS_OFFLINE") == "1"

        # In distributed runs, let rank0 download first to avoid N-way concurrent downloads.
        if torch.distributed.is_available() and torch.distributed.is_initialized():
            if self.rank == 0:
                local_dir = snapshot_download(
                    repo_id=hf_model_path,
                    revision=revision,
                    local_files_only=offline,
                    allow_patterns=[
                        "*.safetensors",
                        "*.bin",
                        "*.index.json",

View on GitHub (pinned to f28afaf635)

Solutions

1. Install huggingface_hub (uv add huggingface_hub / pip install huggingface_hub)
2. Or download/sync the model on a machine with access and pass the local directory as hf_model_path
3. Verify with python -c "import huggingface_hub" in the same environment the trainer runs in

Example fix

# before
hf_model_path = "Qwen/Qwen2.5-7B"  # huggingface_hub missing

# after
# shell: uv add huggingface_hub  (or use a local snapshot)
hf_model_path = "/data/models/Qwen2.5-7B"

import os
if not (os.path.isdir(hf_model_path) or os.path.isfile(hf_model_path)):
    try:
        import huggingface_hub  # noqa: F401
    except ImportError:
        raise SystemExit("huggingface_hub required for hub repo ids; install it or pass a local model dir")

try:
    path = resolve_model_path(hf_model_path)
except ValueError as e:
    if "huggingface_hub is not available" in str(e):
        subprocess.run([sys.executable, "-m", "pip", "install", "huggingface_hub"], check=True)
        path = resolve_model_path(hf_model_path)  # retry after install
    else:
        raise

When it happens

Trigger: Passing a Hub repo id like 'Qwen/Qwen2.5-7B' while huggingface_hub is not installed in the environment (broken venv, trimmed docker image, dependency conflict).

Common situations: Minimal training images that omit huggingface_hub; a pip resolution that uninstalled it; offline air-gapped installs where the package was deliberately excluded.

Related errors

• No checkpoint files found in {hf_model_path}
• The current model does not support `chat`.
• The current model does not support `stream_chat`.
• Cannot get scores using an auto-regressive model.
• Unknown logging level: {env_level_str}.

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