Lightning-AI/pytorch-lightning · critical · MisconfigurationException

The "interval" key in lr scheduler dict must be "step" or "e

Error message

The "interval" key in lr scheduler dict must be "step" or "epoch" but is "{scheduler["interval"]}"

What it means

In a scheduler dict, the optional 'interval' key controls whether the scheduler steps per 'step' or per 'epoch'. Any other value (e.g. 'batch', 'iteration', 'iteration_step') raises MisconfigurationException echoing the bad value.

Source

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

    lr_scheduler_configs = []
    for scheduler in schedulers:
        if isinstance(scheduler, dict):
            # check provided keys
            supported_keys = {field.name for field in fields(LRSchedulerConfig)}
            extra_keys = scheduler.keys() - supported_keys
            if extra_keys:
                rank_zero_warn(
                    f"Found unsupported keys in the lr scheduler dict: {extra_keys}."
                    " HINT: remove them from the output of `configure_optimizers`.",
                    category=RuntimeWarning,
                )
                scheduler = {k: v for k, v in scheduler.items() if k in supported_keys}
            if "scheduler" not in scheduler:
                raise MisconfigurationException(
                    'The lr scheduler dict must have the key "scheduler" with its item being an lr scheduler'
                )
            if "interval" in scheduler and scheduler["interval"] not in ("step", "epoch"):
                raise MisconfigurationException(
                    'The "interval" key in lr scheduler dict must be "step" or "epoch"'
                    f' but is "{scheduler["interval"]}"'
                )
            scheduler["reduce_on_plateau"] = scheduler.get(
                "reduce_on_plateau", isinstance(scheduler["scheduler"], optim.lr_scheduler.ReduceLROnPlateau)
            )
            if scheduler["reduce_on_plateau"] and scheduler.get("monitor") is None:
                raise MisconfigurationException(
                    "The lr scheduler dict must include a monitor when a `ReduceLROnPlateau` scheduler is used."
                    ' For example: {"optimizer": optimizer, "lr_scheduler":'
                    ' {"scheduler": scheduler, "monitor": "your_loss"}}'
                )
            is_one_cycle = isinstance(scheduler["scheduler"], optim.lr_scheduler.OneCycleLR)
            if is_one_cycle and scheduler.get("interval", "epoch") == "epoch":
                rank_zero_warn(
                    "A `OneCycleLR` scheduler is using 'interval': 'epoch'."
                    " Are you sure you didn't mean 'interval': 'step'?",
                    category=RuntimeWarning,

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Use interval="step" or interval="epoch"
2. If you intended per-batch stepping, that is interval="step"

Example fix

# before
{'scheduler': sched, 'interval': 'batch'}
# after
{'scheduler': sched, 'interval': 'step'}

assert interval in ("step", "epoch")

def valid_interval(v: str) -> bool:
    return v in {"step", "epoch"}

When it happens

Trigger: Returning {'scheduler': sched, 'interval': 'batch'} from configure_optimizers.

Common situations: Coming from older Lightning/PyTorch Ignite where the interval was called 'batch' or 'iteration', or typos like 'epochs'.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• The lr scheduler dict must have the key "scheduler" with its
• Some schedulers are attached with an optimizer that wasn't r
• {seed} is not in bounds, numpy accepts from {min_seed_value}
• Expected samples ({samples}) to be greater or equal than bat
• Unknown configuration for model optimizers. Output from `mod

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