Lightning-AI/pytorch-lightning · error · RuntimeError

Error while merging hparams: the keys {inconsistent_keys} ar

Error message

Error while merging hparams: the keys {inconsistent_keys} are present in both the LightningModule's and LightningDataModule's hparams but have different values.

What it means

At the start of training, Lightning merges the LightningModule's and LightningDataModule's hyperparameters for logging; if a key exists in both but with different values (or different types, or non-identical tensors), it raises this RuntimeError because the ambiguity can't be resolved.

Source

Thrown at src/lightning/pytorch/loggers/utilities.py:83

    hparams_initial = None
    if pl_module._log_hyperparams and datamodule_log_hyperparams:
        datamodule_hparams = trainer.datamodule.hparams_initial
        lightning_hparams = pl_module.hparams_initial
        inconsistent_keys = []
        for key in lightning_hparams.keys() & datamodule_hparams.keys():
            if key == "_class_path":
                # Skip LightningCLI's internal hparam
                continue
            lm_val, dm_val = lightning_hparams[key], datamodule_hparams[key]
            if (
                type(lm_val) != type(dm_val)  # noqa: E721
                or (isinstance(lm_val, Tensor) and id(lm_val) != id(dm_val))
                or lm_val != dm_val
            ):
                inconsistent_keys.append(key)
        if inconsistent_keys:
            raise RuntimeError(
                f"Error while merging hparams: the keys {inconsistent_keys} are present "
                "in both the LightningModule's and LightningDataModule's hparams "
                "but have different values."
            )
        hparams_initial = {**lightning_hparams, **datamodule_hparams}
    elif pl_module._log_hyperparams:
        hparams_initial = pl_module.hparams_initial
    elif datamodule_log_hyperparams:
        hparams_initial = trainer.datamodule.hparams_initial

    # Don't log LightningCLI's internal hparam
    if hparams_initial is not None:
        hparams_initial = {k: v for k, v in hparams_initial.items() if k != "_class_path"}

    for logger in trainer.loggers:
        if hparams_initial is not None:
            logger.log_hyperparams(hparams_initial)
        logger.log_graph(pl_module)

View on GitHub (pinned to 9fed5c27d2)

Solutions

Make the values identical (single source of truth: pass the same config value to both)
Remove the duplicated key from one of the two classes' saved hparams (usually the datamodule)
For tensors, pass the same tensor object to both or don't save it as an hparam

Example fix

# before
model = LitModel(batch_size=32)
dm = LitDataModule(batch_size=64)  # same key, different value
trainer.fit(model, datamodule=dm)
# after
bs = cfg.batch_size
model = LitModel(batch_size=bs)
dm = LitDataModule(batch_size=bs)
trainer.fit(model, datamodule=dm)

Defensive patterns

Strategy: validation

Validate before calling

lm_h = dict(model.hparams); dm_h = dict(datamodule.hparams)
overlap = set(lm_h) & set(dm_h)
bad = [k for k in overlap and (type(lm_h[k]) != type(dm_h[k]) or lm_h[k] != dm_h[k])]
assert not bad, f"Mismatched shared hparams: {bad}"

Prevention

Derive both model and datamodule hparams from one config object
Avoid save_hyperparameters of the same key in both classes

When it happens

Trigger: Defining hparams like batch_size=32 on the LightningModule (e.g. via save_hyperparameters) and batch_size=64 on the LightningDataModule, then fitting with a datamodule — comparison uses type equality and value equality (identity for Tensors).

Common situations: Refactoring so both classes expose the same hparam name from argparse/config with stale defaults; passing different values to model and datamodule constructors from a config where they should be shared.

Related errors

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