{"record":{"id":"50bbe6cea4665b7a","repo":"Lightning-AI/pytorch-lightning","slug":"the-type-trainer-strategy-name-does-not-s","errorCode":null,"errorMessage":"The `{type(trainer.strategy).__name__}` does not support `accumulate_grad_batches` changing between epochs.","messagePattern":"The `(.+?)` does not support `accumulate_grad_batches` changing between epochs\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/callbacks/gradient_accumulation_scheduler.py","lineNumber":128,"sourceCode":"                manual optimization. Please remove the callback or switch to automatic optimization.\"\"\"\n            )\n\n        overridden_optimizer_step = is_overridden(\"optimizer_step\", pl_module)\n        overridden_optimizer_zero_grad = is_overridden(\"optimizer_zero_grad\", pl_module)\n        going_to_accumulate_grad_batches = self.going_to_accumulate_grad_batches()\n        has_overridden_optimization_functions = overridden_optimizer_step or overridden_optimizer_zero_grad\n        if has_overridden_optimization_functions and going_to_accumulate_grad_batches:\n            rank_zero_warn(\n                \"When using `Trainer(accumulate_grad_batches != 1)` and overriding\"\n                \" `LightningModule.optimizer_{step,zero_grad}`, the hooks will not be called on every batch\"\n                \" (rather, they are called on every optimization step).\"\n            )\n\n        # local import to avoid circular import\n        from lightning.pytorch.strategies import DeepSpeedStrategy\n\n        if isinstance(trainer.strategy, DeepSpeedStrategy):\n            raise RuntimeError(\n                f\"The `{type(trainer.strategy).__name__}` does not support `accumulate_grad_batches` changing\"\n                \" between epochs.\"\n            )\n        if trainer.accumulate_grad_batches != 1:\n            raise ValueError(\n                \"You have set `accumulate_grad_batches` and are using the `GradientAccumulationScheduler`\"\n                \" callback. Either remove `accumulate_grad_batches` from the Trainer or remove the callback.\"\n            )\n\n    @override\n    def on_train_epoch_start(self, trainer: \"pl.Trainer\", *_: Any) -> None:\n        trainer.accumulate_grad_batches = self.get_accumulate_grad_batches(trainer.current_epoch)\n","sourceCodeStart":110,"sourceCodeEnd":141,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/callbacks/gradient_accumulation_scheduler.py#L110-L141","documentation":"DeepSpeed bakes gradient accumulation into its engine config at initialization, so changing `accumulate_grad_batches` between epochs (which GradientAccumulationScheduler does) cannot be supported. `on_train_start` raises RuntimeError naming the strategy class when it is DeepSpeedStrategy.","triggerScenarios":"`Trainer(strategy='deepspeed', accumulate_grad_batches=..., callbacks=[GradientAccumulationScheduler(...)])` — fails right at train start.","commonSituations":"Adding an epoch-based accumulation schedule for a warmup/curriculum while using DeepSpeed ZeRO; migrating from DDP to DeepSpeed and keeping the callback.","solutions":["Use DeepSpeed's fixed `accumulate_grad_batches` on the Trainer and remove GradientAccumulationScheduler","For dynamic schedules, restart training stages with separate Trainer runs using different fixed accumulation values","If a per-epoch schedule is essential, use a non-DeepSpeed strategy"],"exampleFix":"# before\nTrainer(strategy='deepspeed', callbacks=[GradientAccumulationScheduler({0: 1, 5: 4})])\n# after\nTrainer(strategy='deepspeed', accumulate_grad_batches=4)","handlingStrategy":"validation","validationCode":"from lightning.pytorch.strategies import DeepSpeedStrategy\nif isinstance(trainer.strategy, DeepSpeedStrategy):\n    assert not any(isinstance(c, GradientAccumulationScheduler) for c in callbacks)","typeGuard":"def scheduler_compatible(trainer) -> bool:\n    from lightning.pytorch.strategies import DeepSpeedStrategy\n    return not isinstance(trainer.strategy, DeepSpeedStrategy)","tryCatchPattern":null,"preventionTips":["With DeepSpeed use fixed accumulate_grad_batches only","Test the full callback+strategy combination in a 1-step smoke run in CI"],"tags":["lightning","deepspeed","gradient-accumulation","strategy-incompatible"],"backgroundTag":"strategy-callback-incompatible","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}