Lightning-AI/pytorch-lightning · error · ValueError

You have set `accumulate_grad_batches` and are using the `Gr

Error message

You have set `accumulate_grad_batches` and are using the `GradientAccumulationScheduler` callback. Either remove `accumulate_grad_batches` from the Trainer or remove the callback.

What it means

GradientAccumulationScheduler itself sets `trainer.accumulate_grad_batches` per epoch, so a Trainer-level value other than 1 would conflict. `on_train_start` raises ValueError if `trainer.accumulate_grad_batches != 1`, telling you to remove one of the two mechanisms.

Source

Thrown at src/lightning/pytorch/callbacks/gradient_accumulation_scheduler.py:133

        going_to_accumulate_grad_batches = self.going_to_accumulate_grad_batches()
        has_overridden_optimization_functions = overridden_optimizer_step or overridden_optimizer_zero_grad
        if has_overridden_optimization_functions and going_to_accumulate_grad_batches:
            rank_zero_warn(
                "When using `Trainer(accumulate_grad_batches != 1)` and overriding"
                " `LightningModule.optimizer_{step,zero_grad}`, the hooks will not be called on every batch"
                " (rather, they are called on every optimization step)."
            )

        # local import to avoid circular import
        from lightning.pytorch.strategies import DeepSpeedStrategy

        if isinstance(trainer.strategy, DeepSpeedStrategy):
            raise RuntimeError(
                f"The `{type(trainer.strategy).__name__}` does not support `accumulate_grad_batches` changing"
                " between epochs."
            )
        if trainer.accumulate_grad_batches != 1:
            raise ValueError(
                "You have set `accumulate_grad_batches` and are using the `GradientAccumulationScheduler`"
                " callback. Either remove `accumulate_grad_batches` from the Trainer or remove the callback."
            )

    @override
    def on_train_epoch_start(self, trainer: "pl.Trainer", *_: Any) -> None:
        trainer.accumulate_grad_batches = self.get_accumulate_grad_batches(trainer.current_epoch)

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Delete `accumulate_grad_batches` from the Trainer and encode the desired accumulation in the scheduler dict (e.g. start value `{0: 4}`)
2. Or drop the callback and keep a single fixed Trainer value
3. Note DeepSpeed users hit the previous RuntimeError (291) instead

Example fix

# before
Trainer(accumulate_grad_batches=4, callbacks=[GradientAccumulationScheduler({0: 8})])
# after
Trainer(callbacks=[GradientAccumulationScheduler({0: 4, 5: 8})])

has_scheduler = any(isinstance(c, GradientAccumulationScheduler) for c in callbacks)
if has_scheduler:
    assert trainer_kwargs.get('accumulate_grad_batches', 1) == 1

When it happens

Trigger: `Trainer(accumulate_grad_batches=4, callbacks=[GradientAccumulationScheduler({0: 8})])` — any value besides 1 on the Trainer triggers it at train start (with non-DeepSpeed strategies).

Common situations: Copy-pasting a Trainer that already had accumulate_grad_batches and then adding the scheduler callback; sweeps where both knobs are set independently.

Related errors

• Empty dict cannot be interpreted correct
• Epoch should be an int greater than or equal to 0. Got {list
• Accumulation factor should be an int greater than 0. Got {li
• Epochs indexing from 1, epoch {minimal_epoch} cannot be inte
• Automatic gradient accumulation and the `GradientAccumulatio

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