Lightning-AI/pytorch-lightning · error · MisconfigurationException

You restored a checkpoint with current_epoch={self.trainer.c

Error message

You restored a checkpoint with current_epoch={self.trainer.current_epoch}, but you have set Trainer(max_epochs={self.trainer.max_epochs}).

What it means

Raised in restore_loops after a checkpoint is loaded: the restored current_epoch exceeds the configured max_epochs, which would mean training ends immediately (or loops incorrectly). Lightning refuses instead of silently doing zero epochs. max_epochs=-1 (no limit) or None are exempt.

Source

Thrown at src/lightning/pytorch/trainer/connectors/checkpoint_connector.py:362

            if self.trainer.state.fn == TrainerFn.FITTING:
                fit_loop.load_state_dict(state_dict["fit_loop"])
            elif self.trainer.state.fn == TrainerFn.VALIDATING:
                self.trainer.validate_loop.load_state_dict(state_dict["validate_loop"])
            elif self.trainer.state.fn == TrainerFn.TESTING:
                self.trainer.test_loop.load_state_dict(state_dict["test_loop"])
            elif self.trainer.state.fn == TrainerFn.PREDICTING:
                self.trainer.predict_loop.load_state_dict(state_dict["predict_loop"])

        if self.trainer.state.fn != TrainerFn.FITTING:
            return

        # crash if max_epochs is lower then the current epoch from the checkpoint
        if (
            self.trainer.max_epochs != -1
            and self.trainer.max_epochs is not None
            and self.trainer.current_epoch > self.trainer.max_epochs
        ):
            raise MisconfigurationException(
                f"You restored a checkpoint with current_epoch={self.trainer.current_epoch},"
                f" but you have set Trainer(max_epochs={self.trainer.max_epochs})."
            )

    def restore_optimizers_and_schedulers(self) -> None:
        """Restores the optimizers and learning rate scheduler states from the pre-loaded checkpoint."""
        if not self._loaded_checkpoint:
            return

        if self.trainer.strategy.lightning_restore_optimizer:
            # validation
            if "optimizer_states" not in self._loaded_checkpoint:
                raise KeyError(
                    "Trying to restore optimizer state but checkpoint contains only the model."
                    " This is probably due to `ModelCheckpoint.save_weights_only` being set to `True`."
                )
            self.restore_optimizers()

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Raise the limit: Trainer(max_epochs=<value greater than the restored current_epoch>)
2. Use max_epochs=-1 to disable the epoch cap entirely
3. Start a fresh Trainer without resuming the epoch loop if you only want the weights (load weights via load_from_checkpoint instead of ckpt_path resume)

Example fix

# before
trainer = Trainer(max_epochs=10)
trainer.fit(model, ckpt_path="epoch=9.ckpt")  # restored epoch 9... e.g. restored current_epoch=10 > 10 variants
# after
trainer = Trainer(max_epochs=20)  # or -1
trainer.fit(model, ckpt_path="epoch=9.ckpt")

import torch
ckpt = torch.load(path, map_location="cpu", weights_only=False)
restored = ckpt.get("epoch", -1)
if max_epochs not in (-1, None):
    assert restored < max_epochs, f"restored epoch {restored} >= max_epochs {max_epochs}"

When it happens

Trigger: Resuming a checkpoint from epoch 10 with Trainer(max_epochs=10) or any max_epochs < restored current_epoch; common when retraining with a smaller budget or when max_epochs is mistakenly treated as additional epochs.

Common situations: Users expect fit(ckpt_path=...) to add N more epochs; fine-tuning pipelines that reduce the epoch budget; resuming a finished run to continue training without raising the cap.

Related errors

• `.{fn}(ckpt_path="hpc")` is set but no HPC checkpoint was fo
• `.{fn}()` found no path for the best weights: {ckpt_path!r}.
• Trying to restore optimizer state but checkpoint contains on
• Trying to restore learning rate scheduler state but checkpoi
• The dirpath has changed from {dirpath_from_ckpt!r} to {self.

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