Lightning-AI/pytorch-lightning · error · ValueError

.csv, .yml or .yaml is required for `hparams_file`

Error message

.csv, .yml or .yaml is required for `hparams_file`

What it means

Raised by Lightning's load_from_checkpoint when an hparams_file is supplied whose file extension is not .csv, .yml, or .yaml. The loader dispatches on the file extension to pick a parser (CSV tags file or YAML config); any other extension has no parser, so it rejects the request.

Source

Thrown at src/lightning/pytorch/core/saving.py:85

) -> Union["pl.LightningModule", "pl.LightningDataModule"]:
    map_location = map_location or _default_map_location

    with pl_legacy_patch():
        checkpoint = pl_load(checkpoint_path, map_location=map_location, weights_only=weights_only)

    # convert legacy checkpoints to the new format
    checkpoint = _pl_migrate_checkpoint(
        checkpoint, checkpoint_path=(checkpoint_path if isinstance(checkpoint_path, (str, Path)) else None)
    )

    if hparams_file is not None:
        extension = str(hparams_file).split(".")[-1]
        if extension.lower() == "csv":
            hparams = load_hparams_from_tags_csv(hparams_file)
        elif extension.lower() in ("yml", "yaml"):
            hparams = load_hparams_from_yaml(hparams_file)
        else:
            raise ValueError(".csv, .yml or .yaml is required for `hparams_file`")

        # overwrite hparams by the given file
        checkpoint[cls.CHECKPOINT_HYPER_PARAMS_KEY] = hparams

    # TODO: make this a migration:
    # for past checkpoint need to add the new key
    checkpoint.setdefault(cls.CHECKPOINT_HYPER_PARAMS_KEY, {})
    # override the hparams with values that were passed in
    checkpoint[cls.CHECKPOINT_HYPER_PARAMS_KEY].update(kwargs)

    if issubclass(cls, pl.LightningDataModule):
        return _load_state(cls, checkpoint, **kwargs)
    if issubclass(cls, pl.LightningModule):
        model = _load_state(cls, checkpoint, strict=strict, **kwargs)
        state_dict = checkpoint["state_dict"]
        if not state_dict:
            rank_zero_warn(f"The state dict in {checkpoint_path!r} contains no parameters.")
            return model

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Convert the hparams file to YAML and pass the .yaml path
2. If the file is CSV, ensure it has the .csv extension
3. Convert JSON to YAML with `python -c "import json,yaml;print(yaml.safe_dump(json.load(open('hparams.json'))))" > hparams.yaml` and pass hparams_file='hparams.yaml'

Example fix

// before
model = MyModel.load_from_checkpoint(ckpt, hparams_file="hparams.json")
// after
model = MyModel.load_from_checkpoint(ckpt, hparams_file="hparams.yaml")

from pathlib import Path
ext = Path(hparams_file).suffix.lower().lstrip('.')
assert ext in {"csv", "yml", "yaml"}, f"hparams_file must be .csv/.yml/.yaml, got .{ext}"

When it happens

Trigger: Calling LightningModule.load_from_checkpoint(path, hparams_file='hparams.json') or any hparams_file whose last dot-separated token isn't csv/yml/yaml (including files with no extension, so extension becomes the whole filename).

Common situations: Users saving hyperparameters as JSON (a common format) and passing it as hparams_file, or passing a file with a trailing dot / uppercase variants are fine (lower() applied) but .json or .txt fail.

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/8614c9a7783c116c. Report an issue: GitHub.