{"record":{"id":"8614c9a7783c116c","repo":"Lightning-AI/pytorch-lightning","slug":"csv-yml-or-yaml-is-required-for-hparams-file","errorCode":null,"errorMessage":".csv, .yml or .yaml is required for `hparams_file`","messagePattern":"\\.csv, \\.yml or \\.yaml is required for `hparams_file`","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/core/saving.py","lineNumber":85,"sourceCode":") -> Union[\"pl.LightningModule\", \"pl.LightningDataModule\"]:\n    map_location = map_location or _default_map_location\n\n    with pl_legacy_patch():\n        checkpoint = pl_load(checkpoint_path, map_location=map_location, weights_only=weights_only)\n\n    # convert legacy checkpoints to the new format\n    checkpoint = _pl_migrate_checkpoint(\n        checkpoint, checkpoint_path=(checkpoint_path if isinstance(checkpoint_path, (str, Path)) else None)\n    )\n\n    if hparams_file is not None:\n        extension = str(hparams_file).split(\".\")[-1]\n        if extension.lower() == \"csv\":\n            hparams = load_hparams_from_tags_csv(hparams_file)\n        elif extension.lower() in (\"yml\", \"yaml\"):\n            hparams = load_hparams_from_yaml(hparams_file)\n        else:\n            raise ValueError(\".csv, .yml or .yaml is required for `hparams_file`\")\n\n        # overwrite hparams by the given file\n        checkpoint[cls.CHECKPOINT_HYPER_PARAMS_KEY] = hparams\n\n    # TODO: make this a migration:\n    # for past checkpoint need to add the new key\n    checkpoint.setdefault(cls.CHECKPOINT_HYPER_PARAMS_KEY, {})\n    # override the hparams with values that were passed in\n    checkpoint[cls.CHECKPOINT_HYPER_PARAMS_KEY].update(kwargs)\n\n    if issubclass(cls, pl.LightningDataModule):\n        return _load_state(cls, checkpoint, **kwargs)\n    if issubclass(cls, pl.LightningModule):\n        model = _load_state(cls, checkpoint, strict=strict, **kwargs)\n        state_dict = checkpoint[\"state_dict\"]\n        if not state_dict:\n            rank_zero_warn(f\"The state dict in {checkpoint_path!r} contains no parameters.\")\n            return model","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/core/saving.py#L67-L103","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Convert the hparams file to YAML and pass the .yaml path","If the file is CSV, ensure it has the .csv extension","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'"],"exampleFix":"// before\nmodel = MyModel.load_from_checkpoint(ckpt, hparams_file=\"hparams.json\")\n// after\nmodel = MyModel.load_from_checkpoint(ckpt, hparams_file=\"hparams.yaml\")","handlingStrategy":"validation","validationCode":"from pathlib import Path\next = Path(hparams_file).suffix.lower().lstrip('.')\nassert ext in {\"csv\", \"yml\", \"yaml\"}, f\"hparams_file must be .csv/.yml/.yaml, got .{ext}\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Save hparams as YAML alongside checkpoints","Validate file extensions in your config loader before passing paths"],"tags":["lightning","checkpoint","hparams","file-extension"],"backgroundTag":"unsupported-file-format","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}