{"record":{"id":"6e75e1aec418f201","repo":"hiyouga/LlamaFactory","slug":"hf-model-path-hf-model-path-does-not-exist-loc","errorCode":null,"errorMessage":"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}","messagePattern":"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: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/v1/plugins/trainer_plugins/distributed/fsdp2.py","lineNumber":617,"sourceCode":"\n        - If `hf_model_path` is an existing directory, return it.\n        - If it's a file path, return its parent directory.\n        - Otherwise treat it as a Hugging Face Hub repo id and download/resolve to the local cache dir.\n        \"\"\"\n        if not hf_model_path:\n            return hf_model_path\n\n        # Local directory or file path.\n        if os.path.isdir(hf_model_path):\n            return hf_model_path\n        if os.path.isfile(hf_model_path):\n            return os.path.dirname(hf_model_path)\n\n        # HuggingFace Hub repo id: snapshot to local cache so we can glob/index files.\n        try:\n            from huggingface_hub import snapshot_download\n        except ImportError as e:\n            raise ValueError(\n                f\"hf_model_path='{hf_model_path}' does not exist locally and huggingface_hub is not available \"\n                f\"to download it. Please provide a local model directory or install huggingface_hub. Error: {e}\"\n            ) from e\n\n        revision = os.getenv(\"HF_REVISION\")\n        offline = os.getenv(\"HF_HUB_OFFLINE\") == \"1\" or os.getenv(\"TRANSFORMERS_OFFLINE\") == \"1\"\n\n        # In distributed runs, let rank0 download first to avoid N-way concurrent downloads.\n        if torch.distributed.is_available() and torch.distributed.is_initialized():\n            if self.rank == 0:\n                local_dir = snapshot_download(\n                    repo_id=hf_model_path,\n                    revision=revision,\n                    local_files_only=offline,\n                    allow_patterns=[\n                        \"*.safetensors\",\n                        \"*.bin\",\n                        \"*.index.json\",","sourceCodeStart":599,"sourceCodeEnd":635,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/v1/plugins/trainer_plugins/distributed/fsdp2.py#L599-L635","documentation":"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.","triggerScenarios":"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).","commonSituations":"Minimal training images that omit huggingface_hub; a pip resolution that uninstalled it; offline air-gapped installs where the package was deliberately excluded.","solutions":["Install huggingface_hub (uv add huggingface_hub / pip install huggingface_hub)","Or download/sync the model on a machine with access and pass the local directory as hf_model_path","Verify with python -c \"import huggingface_hub\" in the same environment the trainer runs in"],"exampleFix":"# before\nhf_model_path = \"Qwen/Qwen2.5-7B\"  # huggingface_hub missing\n\n# after\n# shell: uv add huggingface_hub  (or use a local snapshot)\nhf_model_path = \"/data/models/Qwen2.5-7B\"","handlingStrategy":"fallback","validationCode":"import os\nif not (os.path.isdir(hf_model_path) or os.path.isfile(hf_model_path)):\n    try:\n        import huggingface_hub  # noqa: F401\n    except ImportError:\n        raise SystemExit(\"huggingface_hub required for hub repo ids; install it or pass a local model dir\")","typeGuard":null,"tryCatchPattern":"try:\n    path = resolve_model_path(hf_model_path)\nexcept ValueError as e:\n    if \"huggingface_hub is not available\" in str(e):\n        subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"huggingface_hub\"], check=True)\n        path = resolve_model_path(hf_model_path)  # retry after install\n    else:\n        raise","preventionTips":["Include huggingface_hub in training environment definition (uv/lockfile/docker)","Pre-sync models to local storage in air-gapped clusters","Smoke-test imports in the training environment before launch"],"tags":["fsdp2","model-loading","huggingface-hub","environment"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}