Lightning-AI/pytorch-lightning · error · MisconfigurationException

The provided lr scheduler `{scheduler.__class__.__name__}` d

Error message

The provided lr scheduler `{scheduler.__class__.__name__}` doesn't follow PyTorch's LRScheduler API. You should override the `LightningModule.lr_scheduler_step` hook with your own logic if you are using a custom LR scheduler.

What it means

If a scheduler is not one of PyTorch's standard LRScheduler types (LRSchedulerTypeTuple) and the LightningModule does not override the lr_scheduler_step hook while using automatic optimization, Lightning cannot know how to call scheduler.step() and raises MisconfigurationException.

Source

Thrown at src/lightning/pytorch/core/optimizer.py:344

        lr_scheduler_configs.append(config)
    return lr_scheduler_configs


def _validate_scheduler_api(lr_scheduler_configs: list[LRSchedulerConfig], model: "pl.LightningModule") -> None:
    for config in lr_scheduler_configs:
        scheduler = config.scheduler
        if not isinstance(scheduler, _Stateful):
            raise TypeError(
                f"The provided lr scheduler `{scheduler.__class__.__name__}` is invalid."
                " It should have `state_dict` and `load_state_dict` methods defined."
            )

        if (
            not isinstance(scheduler, LRSchedulerTypeTuple)
            and not is_overridden("lr_scheduler_step", model)
            and model.automatic_optimization
        ):
            raise MisconfigurationException(
                f"The provided lr scheduler `{scheduler.__class__.__name__}` doesn't follow PyTorch's LRScheduler"
                " API. You should override the `LightningModule.lr_scheduler_step` hook with your own logic if"
                " you are using a custom LR scheduler."
            )


def _validate_multiple_optimizers_support(optimizers: list[Optimizer], model: "pl.LightningModule") -> None:
    if is_param_in_hook_signature(model.training_step, "optimizer_idx", explicit=True):
        raise RuntimeError(
            "Training with multiple optimizers is only supported with manual optimization. Remove the `optimizer_idx`"
            " argument from `training_step`, set `self.automatic_optimization = False` and access your optimizers"
            " in `training_step` with `opt1, opt2, ... = self.optimizers()`."
        )
    if model.automatic_optimization and len(optimizers) > 1:
        raise RuntimeError(
            "Training with multiple optimizers is only supported with manual optimization. Set"
            " `self.automatic_optimization = False`, then access your optimizers in `training_step` with"
            " `opt1, opt2, ... = self.optimizers()`."

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Override lr_scheduler_step in the LightningModule: def lr_scheduler_step(self, scheduler, metric): scheduler.step(metric) (or scheduler.step())
2. Or refactor the scheduler to subclass torch.optim.lr_scheduler.LRScheduler

Example fix

# before
class LM(pl.LightningModule):
    ...  # custom scheduler, no hook
# after
class LM(pl.LightningModule):
    def lr_scheduler_step(self, scheduler, metric):
        if metric is None:
            scheduler.step()
        else:
            scheduler.step(metric)

from lightning.pytorch.utilities.types import LRSchedulerTypeTuple
from lightning.pytorch.utilities.model_helpers import is_overridden
if not isinstance(sched, LRSchedulerTypeTuple) and not is_overridden("lr_scheduler_step", model):
    raise RuntimeError("override lr_scheduler_step for custom scheduler")

def custom_sched_needs_hook(sched, model) -> bool:
    from lightning.pytorch.utilities.types import LRSchedulerTypeTuple
    from lightning.pytorch.utilities.model_helpers import is_overridden
    return not isinstance(sched, LRSchedulerTypeTuple) and not is_overridden("lr_scheduler_step", model)

When it happens

Trigger: Using a custom scheduler class (not subclassing torch LRScheduler) with automatic_optimization=True and no lr_scheduler_step override.

Common situations: Custom cyclic/warmup schedulers or third-party schedulers (e.g. from transformers) that expose step(epoch, metric) signatures unlike PyTorch's.

Related errors

• The lr scheduler dict must have the key "scheduler" with its
• The "interval" key in lr scheduler dict must be "step" or "e
• `configure_optimizers` must include a monitor when a `Reduce
• The provided lr scheduler `{scheduler.__class__.__name__}` i
• Some schedulers are attached with an optimizer that wasn't r

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