{"record":{"id":"3646c4fdc6ac7880","repo":"Lightning-AI/pytorch-lightning","slug":"trying-to-restore-learning-rate-scheduler-state-bu","errorCode":null,"errorMessage":"Trying to restore learning rate scheduler state but checkpoint contains only the model. This is probably due to `ModelCheckpoint.save_weights_only` being set to `True`.","messagePattern":"Trying to restore learning rate scheduler state but checkpoint contains only the model\\. This is probably due to `ModelCheckpoint\\.save_weights_only` being set to `True`\\.","errorType":"validation","errorClass":"KeyError","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/trainer/connectors/checkpoint_connector.py","lineNumber":382,"sourceCode":"                f\" but you have set Trainer(max_epochs={self.trainer.max_epochs}).\"\n            )\n\n    def restore_optimizers_and_schedulers(self) -> None:\n        \"\"\"Restores the optimizers and learning rate scheduler states from the pre-loaded checkpoint.\"\"\"\n        if not self._loaded_checkpoint:\n            return\n\n        if self.trainer.strategy.lightning_restore_optimizer:\n            # validation\n            if \"optimizer_states\" not in self._loaded_checkpoint:\n                raise KeyError(\n                    \"Trying to restore optimizer state but checkpoint contains only the model.\"\n                    \" This is probably due to `ModelCheckpoint.save_weights_only` being set to `True`.\"\n                )\n            self.restore_optimizers()\n\n        if \"lr_schedulers\" not in self._loaded_checkpoint:\n            raise KeyError(\n                \"Trying to restore learning rate scheduler state but checkpoint contains only the model.\"\n                \" This is probably due to `ModelCheckpoint.save_weights_only` being set to `True`.\"\n            )\n        self.restore_lr_schedulers()\n\n    def restore_optimizers(self) -> None:\n        \"\"\"Restores the optimizer states from the pre-loaded checkpoint.\"\"\"\n        if not self._loaded_checkpoint:\n            return\n\n        # restore the optimizers\n        self.trainer.strategy.load_optimizer_state_dict(self._loaded_checkpoint)\n\n    def restore_lr_schedulers(self) -> None:\n        \"\"\"Restores the learning rate scheduler states from the pre-loaded checkpoint.\"\"\"\n        if not self._loaded_checkpoint:\n            return\n","sourceCodeStart":364,"sourceCodeEnd":400,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/trainer/connectors/checkpoint_connector.py#L364-L400","documentation":"Companion to the optimizer error: raised when the strategy restores training state and the checkpoint is missing the 'lr_schedulers' key, i.e., it was saved with ModelCheckpoint(save_weights_only=True). Learning-rate scheduler state cannot be restored from a weights-only file.","triggerScenarios":"Same as 552: trainer.fit(model, ckpt_path=<weights-only checkpoint>) where lightning_restore_optimizer applies; the optimizer key may exist if schedulers alone were excluded, but typically both are missing.","commonSituations":"Resuming from artifacts saved for inference; HuggingFace-style released checkpoints; switching checkpoint config between experiments.","solutions":["Save checkpoints with save_weights_only=False to include lr_schedulers and optimizer states","Load weights only and initialize a new scheduler (fresh training loop) instead of resuming","Resume from a complete checkpoint file that was saved with full training state"],"exampleFix":"# before\ntrainer.fit(model, ckpt_path=\"weights_only.ckpt\")  # KeyError: lr_schedulers\n# after\nModelCheckpoint(save_weights_only=False)  # during original fit\ntrainer.fit(model, ckpt_path=\"full_state.ckpt\")","handlingStrategy":"validation","validationCode":"import torch\nckpt = torch.load(path, map_location=\"cpu\", weights_only=False)\nassert \"lr_schedulers\" in ckpt and \"optimizer_states\" in ckpt, \"weights-only checkpoint cannot resume scheduler state\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pair resume flows with full-state checkpoints","Write a pre-resume check helper that verifies required keys"],"tags":["lightning","resume","lr-scheduler","weights-only","checkpoint"],"backgroundTag":"weights-only-checkpoint-resume","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}