{"record":{"id":"b87e3d32321f9cd6","repo":"Lightning-AI/pytorch-lightning","slug":"combination-of-parameters-every-n-train-steps-sel","errorCode":null,"errorMessage":"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.","messagePattern":"Combination of parameters every_n_train_steps=(.+?), every_n_epochs=(.+?) and train_time_interval=(.+?) should be mutually exclusive\\.","errorType":"validation","errorClass":"MisconfigurationException","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/callbacks/model_checkpoint.py","lineNumber":680,"sourceCode":"        # if the user runs validation multiple times per training epoch, then we run after validation\n        # instead of on train epoch end\n        return trainer.val_check_interval == 1.0\n\n    def __validate_init_configuration(self) -> None:\n        if self.save_top_k < -1:\n            raise MisconfigurationException(f\"Invalid value for save_top_k={self.save_top_k}. Must be >= -1\")\n        if self._every_n_train_steps < 0:\n            raise MisconfigurationException(\n                f\"Invalid value for every_n_train_steps={self._every_n_train_steps}. Must be >= 0\"\n            )\n        if self._every_n_epochs < 0:\n            raise MisconfigurationException(f\"Invalid value for every_n_epochs={self._every_n_epochs}. Must be >= 0\")\n\n        every_n_train_steps_triggered = self._every_n_train_steps >= 1\n        every_n_epochs_triggered = self._every_n_epochs >= 1\n        train_time_interval_triggered = self._train_time_interval is not None\n        if every_n_train_steps_triggered + every_n_epochs_triggered + train_time_interval_triggered > 1:\n            raise MisconfigurationException(\n                f\"Combination of parameters every_n_train_steps={self._every_n_train_steps}, \"\n                f\"every_n_epochs={self._every_n_epochs} and train_time_interval={self._train_time_interval} \"\n                \"should be mutually exclusive.\"\n            )\n\n        if self.monitor is None and self.save_top_k not in (-1, 0, 1):\n            # -1: save all epochs, 0: nothing is saved, 1: save last epoch\n            raise MisconfigurationException(\n                f\"ModelCheckpoint(save_top_k={self.save_top_k}, monitor=None) is not a valid\"\n                \" configuration. No quantity for top_k to track.\"\n            )\n\n    def __init_ckpt_dir(self, dirpath: Optional[_PATH], filename: Optional[str]) -> None:\n        self._fs = get_filesystem(dirpath if dirpath else \"\")\n\n        if dirpath and _is_local_file_protocol(dirpath if dirpath else \"\"):\n            dirpath = os.path.realpath(os.path.expanduser(dirpath))\n","sourceCodeStart":662,"sourceCodeEnd":698,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/callbacks/model_checkpoint.py#L662-L698","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Keep exactly one frequency parameter >= 1 (or a non-None train_time_interval) and set the others to 0/None","If you need both step- and epoch-based saves, run two ModelCheckpoint instances with different dirpath/filename","Remove leftover legacy parameters (period, save_step_frequency) after migrating to the new API"],"exampleFix":"# before\nModelCheckpoint(every_n_train_steps=500, every_n_epochs=1)\n# after\nModelCheckpoint(every_n_train_steps=500, every_n_epochs=0)","handlingStrategy":"validation","validationCode":"active = [\n    cfg.get('every_n_train_steps', 0) >= 1,\n    cfg.get('every_n_epochs', 0) >= 1,\n    cfg.get('train_time_interval') is not None,\n]\nassert sum(active) <= 1, 'Only one checkpoint frequency trigger may be active'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set unused frequency parameters explicitly to 0/None to avoid accidental defaults","When migrating from period/save_step_frequency, remove old keys"],"tags":["pytorch-lightning","modelcheckpoint","mutually-exclusive-args","config-validation"],"backgroundTag":"mutually-exclusive-arguments","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}