Lightning-AI/pytorch-lightning · error · MisconfigurationException

Invalid value for every_n_epochs={self._every_n_epochs}. Mus

Error message

Invalid value for every_n_epochs={self._every_n_epochs}. Must be >= 0

What it means

ModelCheckpoint raises this when every_n_epochs, the epoch-based checkpointing frequency, is negative. Like the other frequency parameters, 0 means 'disabled' and any value below 0 is rejected during __init__ validation (__validate_init_configuration).

Source

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

        num_val_batches = (
            sum(trainer.num_val_batches) if isinstance(trainer.num_val_batches, list) else trainer.num_val_batches
        )
        if num_val_batches == 0:
            return True

        # 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."
            )

View on GitHub (pinned to 9fed5c27d2)

Solutions

  1. Set every_n_epochs to a positive integer (e.g., 1) or 0 to disable epoch-based saving
  2. Use save_top_k=-1 if the intent was to keep all checkpoints
  3. Validate numeric config values before constructing the callback

Example fix

# before
ModelCheckpoint(every_n_epochs=-1)
# after
ModelCheckpoint(every_n_epochs=1, save_top_k=-1)
Defensive patterns

Strategy: validation

Validate before calling

assert cfg.get('every_n_epochs', 0) >= 0

Type guard

def valid_epoch_interval(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and v >= 0

Prevention

When it happens

Trigger: Passing every_n_epochs=-1 or any negative number to ModelCheckpoint; frequently the result of arithmetic like val_check_interval-derived values, config templating mistakes, or intending save_top_k=-1 semantics.

Common situations: Config files with -1 placeholders; scripts computing every_n_epochs from dataset size and accidentally producing a negative number; confusion between save_top_k's -1 convention and frequency parameters.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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