{"record":{"id":"8f86b6199c28c5bd","repo":"Lightning-AI/pytorch-lightning","slug":"download-model-failed-model-registry","errorCode":null,"errorMessage":"Download model failed - {model_registry}","messagePattern":"Download model failed - (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"src/lightning/pytorch/utilities/model_registry.py","lineNumber":176,"sourceCode":"\ndef download_model_from_registry(ckpt_path: Optional[_PATH], trainer: \"pl.Trainer\") -> None:\n    \"\"\"Download a model from the Lightning Model Registry.\"\"\"\n    if trainer.local_rank == 0:\n        if not module_available(\"litmodels\"):\n            raise ImportError(\n                \"The `litmodels` package is not installed. Please install it with `pip install litmodels`.\"\n            )\n\n        from litmodels import download_model\n\n        model_registry = _determine_model_name(ckpt_path, trainer._model_registry)\n        local_model_dir = _determine_model_folder(model_registry, trainer.default_root_dir)\n\n        # print(f\"Rank {self.trainer.local_rank} downloads model checkpoint '{model_registry}'\")\n        model_files = download_model(model_registry, download_dir=local_model_dir)\n        # print(f\"Model checkpoint '{model_registry}' was downloaded to '{local_model_dir}'\")\n        if not model_files:\n            raise RuntimeError(f\"Download model failed - {model_registry}\")\n\n    trainer.strategy.barrier(\"download_model_from_registry\")\n","sourceCodeStart":158,"sourceCodeEnd":179,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/utilities/model_registry.py#L158-L179","documentation":"Raised when download_model() returns an empty list while fetching a model from a model registry (e.g. HuggingFace/registry backend) into the trainer's default_root_dir. It means the registry identifier resolved but no model files were actually downloaded. Occurs inside trainer fit/validate/test/predict when a model_registry is configured.","triggerScenarios":"Passing a model_registry (e.g. HF repo id) whose snapshot contains no downloadable model files, or a registry path with only unsupported file types; network/permission issues causing silent empty downloads.","commonSituations":"Wrong repo id pointing to an empty/nonexistent revision, private model without credentials, or a registry storing files under unsupported extensions.","solutions":["Verify the registry identifier exists and contains model files (e.g. list the repo with huggingface_hub)","Check authentication/permissions for private registries (HF_TOKEN or login)","Test download manually: download_model('<registry>', download_dir='/tmp/x') and inspect the result","Catch RuntimeError in the training script and fail with a clearer message"],"exampleFix":"// before\ntrainer.fit(model)  # model_registry configured, raises RuntimeError: Download model failed\n// after\nfiles = download_model(registry_id, download_dir='/tmp/chk')\nassert files, f'no files in {registry_id}'\ntrainer.fit(model)","handlingStrategy":"try-catch","validationCode":"from lightning.fabric.utilities.imports import _HOROVOD_AVAILABLE  # noqa\n# simpler: pre-check the registry contents\ntry:\n    from lightning.pytorch.utilities.model_registry import download_model\n    assert download_model(registry_id, download_dir='/tmp/pre') != []\nexcept Exception as e:\n    raise RuntimeError(f'Registry {registry_id} unusable: {e}')","typeGuard":null,"tryCatchPattern":"try:\n    trainer.fit(model)\nexcept RuntimeError as e:\n    if 'Download model failed' in str(e):\n        log.error('registry %s empty or unreachable', registry_id)\n        raise","preventionTips":["Verify registry contents before wiring into the Trainer","Keep credentials (HF token) configured for private registries","Wrap fit/predict with a pre-flight download check in pipelines"],"tags":["model-registry","download","lightning","checkpoint"],"backgroundTag":"artifact-download-failed","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}