Lightning-AI/pytorch-lightning · error · MisconfigurationException

Invalid value for every_n_train_steps={self._every_n_train_s

Error message

Invalid value for every_n_train_steps={self._every_n_train_steps}. Must be >= 0

What it means

ModelCheckpoint validates its checkpointing-frequency configuration at construction time. every_n_train_steps controls how often (in training steps) a checkpoint is saved, and a negative value is meaningless, so the callback raises MisconfigurationException immediately in __init__ (via __validate_init_configuration). The value 0 is allowed and means 'disabled'.

Source

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

        if trainer.check_val_every_n_epoch != 1:
            return False

        # no validation means save on train epoch end
        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(

View on GitHub (pinned to 9fed5c27d2)

Solutions

  1. Set every_n_train_steps to a positive integer (e.g., 1000) or 0 to disable step-based checkpointing
  2. If you wanted 'save everything', use save_top_k=-1 instead, since the -1 convention applies only to save_top_k
  3. Sanitize values read from config files before passing them to ModelCheckpoint

Example fix

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

Strategy: validation

Validate before calling

every_n = cfg.get('every_n_train_steps', 0)
assert isinstance(every_n, int) and every_n >= 0, f"every_n_train_steps must be >= 0, got {every_n}"

Type guard

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

Prevention

When it happens

Trigger: Instantiating ModelCheckpoint(every_n_train_steps=-1) or any negative value; often caused by passing a computed/int-derived value (e.g., a fraction, a subtraction result, or a value loaded from a config file) that evaluates to a negative number.

Common situations: Typos or off-by-one math in training scripts; YAML/JSON config files where every_n_train_steps is set to -1 intending 'save every step' or 'unlimited' (that semantic belongs to save_top_k=-1); copying save_top_k semantics onto the steps parameter.

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/97d118479abe208a. Report an issue: GitHub.