Lightning-AI/pytorch-lightning · error · MisconfigurationException

Combination of parameters every_n_train_steps={self._every_n

Error message

Combination of parameters every_n_train_steps={self._every_n_train_steps}, every_n_epochs={self._every_n_epochs} and train_time_interval={self._train_time_interval} should be mutually exclusive.

What it means

ModelCheckpoint supports three alternative save-frequency triggers: every_n_train_steps, every_n_epochs, and train_time_interval. Only one of them may be active (>=1 / not None) at a time; if two or more are triggered simultaneously, __init__ validation fails because the checkpointing schedule would be ambiguous.

Source

Thrown at src/lightning/pytorch/callbacks/model_checkpoint.py:680

        # if the user runs validation multiple times per training epoch, then we run after validation
        # instead of on train epoch end
        return trainer.val_check_interval == 1.0

    def __validate_init_configuration(self) -> None:
        if self.save_top_k < -1:
            raise MisconfigurationException(f"Invalid value for save_top_k={self.save_top_k}. Must be >= -1")
        if self._every_n_train_steps < 0:
            raise MisconfigurationException(
                f"Invalid value for every_n_train_steps={self._every_n_train_steps}. Must be >= 0"
            )
        if self._every_n_epochs < 0:
            raise MisconfigurationException(f"Invalid value for every_n_epochs={self._every_n_epochs}. Must be >= 0")

        every_n_train_steps_triggered = self._every_n_train_steps >= 1
        every_n_epochs_triggered = self._every_n_epochs >= 1
        train_time_interval_triggered = self._train_time_interval is not None
        if every_n_train_steps_triggered + every_n_epochs_triggered + train_time_interval_triggered > 1:
            raise MisconfigurationException(
                f"Combination of parameters every_n_train_steps={self._every_n_train_steps}, "
                f"every_n_epochs={self._every_n_epochs} and train_time_interval={self._train_time_interval} "
                "should be mutually exclusive."
            )

        if self.monitor is None and self.save_top_k not in (-1, 0, 1):
            # -1: save all epochs, 0: nothing is saved, 1: save last epoch
            raise MisconfigurationException(
                f"ModelCheckpoint(save_top_k={self.save_top_k}, monitor=None) is not a valid"
                " configuration. No quantity for top_k to track."
            )

    def __init_ckpt_dir(self, dirpath: Optional[_PATH], filename: Optional[str]) -> None:
        self._fs = get_filesystem(dirpath if dirpath else "")

        if dirpath and _is_local_file_protocol(dirpath if dirpath else ""):
            dirpath = os.path.realpath(os.path.expanduser(dirpath))

View on GitHub (pinned to 9fed5c27d2)

Solutions

  1. Keep exactly one frequency parameter >= 1 (or a non-None train_time_interval) and set the others to 0/None
  2. If you need both step- and epoch-based saves, run two ModelCheckpoint instances with different dirpath/filename
  3. Remove leftover legacy parameters (period, save_step_frequency) after migrating to the new API

Example fix

# before
ModelCheckpoint(every_n_train_steps=500, every_n_epochs=1)
# after
ModelCheckpoint(every_n_train_steps=500, every_n_epochs=0)
Defensive patterns

Strategy: validation

Validate before calling

active = [
    cfg.get('every_n_train_steps', 0) >= 1,
    cfg.get('every_n_epochs', 0) >= 1,
    cfg.get('train_time_interval') is not None,
]
assert sum(active) <= 1, 'Only one checkpoint frequency trigger may be active'

Prevention

When it happens

Trigger: Passing e.g. every_n_train_steps=100 together with every_n_epochs=1, or every_n_epochs=1 together with train_time_interval=timedelta(minutes=5). Note the legacy parameters save_step_frequency/period map onto these, so old scripts converted to the new API can set two at once.

Common situations: Migrating old code that used `period` or `save_step_frequency` and then also setting the new explicit parameters; copy-pasting a checkpoint config that sets both steps and epochs; defaults changed across Lightning versions so a previously-defaulted parameter is now explicitly set.

Related errors

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