Lightning-AI/pytorch-lightning · error · IndexError

Epochs indexing from 1, epoch {minimal_epoch} cannot be inte

Error message

Epochs indexing from 1, epoch {minimal_epoch} cannot be interpreted correct

What it means

After the earlier per-key check rejects negative keys, this `min(keys) < 0` IndexError is effectively unreachable defensive code. It exists to reject schedules whose first epoch is negative, with a legacy message implying epochs index from 1. In practice you will always hit the MisconfigurationException at line 74 instead.

Source

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

    def __init__(self, scheduling: dict[int, int]):
        super().__init__()

        if not scheduling:  # empty dict error
            raise TypeError("Empty dict cannot be interpreted correct")

        if any(not isinstance(key, int) or key < 0 for key in scheduling):
            raise MisconfigurationException(
                f"Epoch should be an int greater than or equal to 0. Got {list(scheduling.keys())}."
            )

        if any(not isinstance(value, int) or value < 1 for value in scheduling.values()):
            raise MisconfigurationException(
                f"Accumulation factor should be an int greater than 0. Got {list(scheduling.values())}."
            )

        minimal_epoch = min(scheduling.keys())
        if minimal_epoch < 0:
            raise IndexError(f"Epochs indexing from 1, epoch {minimal_epoch} cannot be interpreted correct")
        if minimal_epoch != 0:  # if user didn't define first epoch accumulation factor
            scheduling.update({0: 1})

        self.scheduling = scheduling
        self.epochs = sorted(scheduling.keys())

    def going_to_accumulate_grad_batches(self) -> bool:
        return any(v > 1 for v in self.scheduling.values())

    def get_accumulate_grad_batches(self, epoch: int) -> int:
        accumulate_grad_batches = 1
        for iter_epoch in reversed(self.epochs):
            if epoch >= iter_epoch:
                accumulate_grad_batches = self.scheduling[iter_epoch]
                break
        return accumulate_grad_batches

    @override

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Fix any negative epoch keys to be >= 0 — you'll normally get the clearer MisconfigurationException
2. Upgrade Lightning to get the well-ordered validation
3. If you truly see this error, report it as a bug since the guard is defensive

assert all(k >= 0 for k in scheduling), 'epoch keys must be >= 0'

When it happens

Trigger: Practically none in current versions — negative keys are caught by the preceding check. Only reachable via integer-like objects that pass `isinstance(key, int)` yet compare oddly (e.g. bools, which are ints but never negative).

Common situations: Legacy documentation referencing 'epochs indexing from 1'; users on very old Lightning versions where the check order differed.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

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
• Automatic gradient accumulation and the `GradientAccumulatio
• The `{type(trainer.strategy).__name__}` does not support `ac

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