Lightning-AI/pytorch-lightning · error · MisconfigurationException

Automatic gradient accumulation is not supported for manual

Error message

Automatic gradient accumulation is not supported for manual optimization. Remove `Trainer(accumulate_grad_batches={trainer.accumulate_grad_batches})` or switch to automatic optimization.

What it means

Gradient accumulation via `Trainer(accumulate_grad_batches=k)` only works with automatic optimization; Lightning rejects any value != 1 when `automatic_optimization=False` because it cannot interleave accumulation with your manual optimizer stepping.

Source

Thrown at src/lightning/pytorch/trainer/configuration_validator.py:129

            raise NotImplementedError(
                f"Support for `{epoch_end_name}` has been removed in v2.0.0. `{type(model).__name__}` implements this"
                f" method. You can use the `on_{epoch_end_name}` hook instead. To access outputs, save them in-memory"
                " as instance attributes."
                " You can find migration examples in https://github.com/Lightning-AI/pytorch-lightning/pull/16520."
            )


def __verify_manual_optimization_support(trainer: "pl.Trainer", model: "pl.LightningModule") -> None:
    if model.automatic_optimization:
        return
    if trainer.gradient_clip_val is not None and trainer.gradient_clip_val > 0:
        raise MisconfigurationException(
            "Automatic gradient clipping is not supported for manual optimization."
            f" Remove `Trainer(gradient_clip_val={trainer.gradient_clip_val})`"
            " or switch to automatic optimization."
        )
    if trainer.accumulate_grad_batches != 1:
        raise MisconfigurationException(
            "Automatic gradient accumulation is not supported for manual optimization."
            f" Remove `Trainer(accumulate_grad_batches={trainer.accumulate_grad_batches})`"
            " or switch to automatic optimization."
        )


def __warn_dataloader_iter_limitations(model: "pl.LightningModule") -> None:
    """Check if `dataloader_iter is enabled`."""
    if any(
        is_param_in_hook_signature(step_fn, "dataloader_iter", explicit=True)
        for step_fn in (model.training_step, model.validation_step, model.predict_step, model.test_step)
        if step_fn is not None
    ):
        rank_zero_warn(
            "You are using the `dataloader_iter` step flavor. If you consume the iterator more than once per step, the"
            " `batch_idx` argument in any hook that takes it will not match with the batch index of the last batch"
            " consumed. This might have unforeseen effects on callbacks or code that expects to get the correct index."
            " This will also not work well with gradient accumulation. This feature is very experimental and subject to"

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Set `accumulate_grad_batches=1` (remove it) for the manual-optimization model.
2. Implement accumulation yourself: only call `optimizer.step()`/`zero_grad()` every N batches using `self.global_step` or a counter.
3. Switch to automatic optimization to keep Trainer-level accumulation.

Example fix

# before
trainer = Trainer(accumulate_grad_batches=8)  # manual opt model
# after
trainer = Trainer()
# in training_step, step every 8 batches:
# if (self._step + 1) % 8 == 0: opt.step(); opt.zero_grad()

def validate_accumulation(model, trainer_kwargs):
    if getattr(model, 'automatic_optimization', True) is False and trainer_kwargs.get('accumulate_grad_batches', 1) != 1:
        raise ValueError('Set accumulate_grad_batches=1 and accumulate manually in training_step')
    return trainer_kwargs

def needs_manual_accumulation(model) -> bool:
    return model.automatic_optimization is False

except MisconfigurationException as e: if 'gradient accumulation' in str(e): rebuild Trainer with accumulate_grad_batches=1 and add custom stepping

When it happens

Trigger: `LightningModule.automatic_optimization = False` plus `Trainer(accumulate_grad_batches=4)` (or scheduler-dict accumulation settings).

Common situations: Memory-saving accumulation configs reused with GAN/RL manual-optimization code; accumulation set via a shared config file used by both types of modules.

Related errors

• Automatic gradient clipping is not supported for manual opti
• Blocking backward sync is only possible if the module passed
• Automatic gradient accumulation and the `GradientAccumulatio
• to use {fn_name}, please disable automatic optimization: set
• `max_epochs` must be a non-negative integer or -1. You passe

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