{"record":{"id":"97d118479abe208a","repo":"Lightning-AI/pytorch-lightning","slug":"invalid-value-for-every-n-train-steps-self-every","errorCode":null,"errorMessage":"Invalid value for every_n_train_steps={self._every_n_train_steps}. Must be >= 0","messagePattern":"Invalid value for every_n_train_steps=(.+?)\\. Must be >= 0","errorType":"validation","errorClass":"MisconfigurationException","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/callbacks/model_checkpoint.py","lineNumber":670,"sourceCode":"        if trainer.check_val_every_n_epoch != 1:\n            return False\n\n        # no validation means save on train epoch end\n        num_val_batches = (\n            sum(trainer.num_val_batches) if isinstance(trainer.num_val_batches, list) else trainer.num_val_batches\n        )\n        if num_val_batches == 0:\n            return True\n\n        # 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(","sourceCodeStart":652,"sourceCodeEnd":688,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/callbacks/model_checkpoint.py#L652-L688","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set every_n_train_steps to a positive integer (e.g., 1000) or 0 to disable step-based checkpointing","If you wanted 'save everything', use save_top_k=-1 instead, since the -1 convention applies only to save_top_k","Sanitize values read from config files before passing them to ModelCheckpoint"],"exampleFix":"# before\nModelCheckpoint(every_n_train_steps=-1)\n# after\nModelCheckpoint(save_top_k=-1, every_n_train_steps=0)","handlingStrategy":"validation","validationCode":"every_n = cfg.get('every_n_train_steps', 0)\nassert isinstance(every_n, int) and every_n >= 0, f\"every_n_train_steps must be >= 0, got {every_n}\"","typeGuard":"def valid_step_interval(v) -> bool:\n    return isinstance(v, int) and not isinstance(v, bool) and v >= 0","tryCatchPattern":null,"preventionTips":["Treat 0 as 'disabled' and never pass negative frequency values","Validate numeric hyperparameters from YAML/JSON before callback construction"],"tags":["pytorch-lightning","modelcheckpoint","config-validation","argument-validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}