Lightning-AI/pytorch-lightning · critical · RuntimeError

Download model failed - {model_registry}

Error message

Download model failed - {model_registry}

What it means

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.

Source

Thrown at src/lightning/pytorch/utilities/model_registry.py:176

def download_model_from_registry(ckpt_path: Optional[_PATH], trainer: "pl.Trainer") -> None:
    """Download a model from the Lightning Model Registry."""
    if trainer.local_rank == 0:
        if not module_available("litmodels"):
            raise ImportError(
                "The `litmodels` package is not installed. Please install it with `pip install litmodels`."
            )

        from litmodels import download_model

        model_registry = _determine_model_name(ckpt_path, trainer._model_registry)
        local_model_dir = _determine_model_folder(model_registry, trainer.default_root_dir)

        # print(f"Rank {self.trainer.local_rank} downloads model checkpoint '{model_registry}'")
        model_files = download_model(model_registry, download_dir=local_model_dir)
        # print(f"Model checkpoint '{model_registry}' was downloaded to '{local_model_dir}'")
        if not model_files:
            raise RuntimeError(f"Download model failed - {model_registry}")

    trainer.strategy.barrier("download_model_from_registry")

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Verify the registry identifier exists and contains model files (e.g. list the repo with huggingface_hub)
2. Check authentication/permissions for private registries (HF_TOKEN or login)
3. Test download manually: download_model('<registry>', download_dir='/tmp/x') and inspect the result
4. Catch RuntimeError in the training script and fail with a clearer message

Example fix

// before
trainer.fit(model)  # model_registry configured, raises RuntimeError: Download model failed
// after
files = download_model(registry_id, download_dir='/tmp/chk')
assert files, f'no files in {registry_id}'
trainer.fit(model)

from lightning.fabric.utilities.imports import _HOROVOD_AVAILABLE  # noqa
# simpler: pre-check the registry contents
try:
    from lightning.pytorch.utilities.model_registry import download_model
    assert download_model(registry_id, download_dir='/tmp/pre') != []
except Exception as e:
    raise RuntimeError(f'Registry {registry_id} unusable: {e}')

try:
    trainer.fit(model)
except RuntimeError as e:
    if 'Download model failed' in str(e):
        log.error('registry %s empty or unreachable', registry_id)
        raise

When it happens

Trigger: 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.

Common situations: Wrong repo id pointing to an empty/nonexistent revision, private model without credentials, or a registry storing files under unsupported extensions.

Related errors

• Could not find a distributed model in the provided checkpoin
• Found multiple distributed models in the given state. Loadin
• The path {str(path)!r} does not point to a valid checkpoint.
• Failed to load checkpoint directly into the model. The given
• The model contains a key '{full_param_name}' that does not e

AI-assisted analysis of Lightning-AI/pytorch-lightning@9fed5c27d2 (2026-08-28). Data as JSON: /api/errors/8f86b6199c28c5bd. Report an issue: GitHub.