Lightning-AI/pytorch-lightning · error · TypeError

hparams must be dictionary

Error message

hparams must be dictionary

What it means

TypeError from save_hparams_to_yaml after Namespace/AttributeDict conversion and the OmegaConf fallback path: if hparams is still not a plain dict, it cannot be serialized to YAML by this function.

Source

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

    # saving with OmegaConf objects
    if _OMEGACONF_AVAILABLE and use_omegaconf:
        from omegaconf import OmegaConf
        from omegaconf.dictconfig import DictConfig
        from omegaconf.errors import UnsupportedValueType, ValidationError

        # deepcopy: hparams from user shouldn't be resolved
        hparams = deepcopy(hparams)
        hparams = apply_to_collection(hparams, DictConfig, OmegaConf.to_container, resolve=True)
        with fs.open(config_yaml, "w", encoding="utf-8") as fp:
            try:
                OmegaConf.save(hparams, fp)
                return
            except (UnsupportedValueType, ValidationError):
                pass

    if not isinstance(hparams, dict):
        raise TypeError("hparams must be dictionary")

    hparams_allowed = {}
    # drop parameters which contain some strange datatypes as fsspec
    for k, v in hparams.items():
        try:
            v = v.name if isinstance(v, Enum) else v
            yaml.dump(v)
        except (TypeError, ValueError):
            warn(f"Skipping '{k}' parameter because it is not possible to safely dump to YAML.")
            hparams[k] = type(v).__name__
        else:
            hparams_allowed[k] = v

    # saving the standard way
    with fs.open(config_yaml, "w", newline="") as fp:
        yaml.dump(hparams_allowed, fp)

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Convert to a plain dict first: hparams = dict(hparams) (or OmegaConf.to_container(hparams, resolve=True) for configs)
2. Replace non-serializable values (tensors, objects) with primitives before saving
3. For dataclasses use dataclasses.asdict(hparams)

Example fix

// before
save_hparams_to_yaml(path, OmegaConf.create({"lr": tensor_obj}))  # falls through
// after
from omegaconf import OmegaConf
hparams = OmegaConf.to_container(cfg, resolve=True)
save_hparams_to_yaml(path, hparams)

if not isinstance(hparams, dict):
    hparams = OmegaConf.to_container(hparams, resolve=True) if OmegaConf.is_config(hparams) else dict(hparams)

def is_plain_dict(x) -> bool:
    return type(x) is dict

When it happens

Trigger: Passing a dataclass, omegaconf DictConfig that failed OmegaConf.save with UnsupportedValueType/ValidationError and fell through, a custom Mapping subclass, or a string/None as hparams.

Common situations: Hyperparameters stored in a dataclass or a DictConfig containing non-serializable values (tensors, custom objects); the OmegaConf save attempt fails, then the dict check trips.

Related errors

• Missing folder: {os.path.dirname(config_yaml)}.
• `name` must be a str, found {name}
• Expected `torch.nn.Module` or `torch.optim.Optimizer`, got:
• The provided lr scheduler `{scheduler.__class__.__name__}` i
• .csv, .yml or .yaml is required for `hparams_file`

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