tracel-ai/burn · error

`.step()` should be called no more than `i32::MAX + 1` times

Error message

`.step()` should be called no more than `i32::MAX + 1` times

What it means

Overflow guard in `StepLrScheduler::step`: the iteration index is stored as `i32` (to avoid exponent truncation when applying `gamma^iter_idx`); calling step past `i32::MAX + 1` times would overflow, so the scheduler panics instead.

Source

Thrown at crates/burn-optim/src/lr_scheduler/step.rs:92

}

/// Step learning rate scheduler.
#[derive(Clone, Debug)]
pub struct StepLrScheduler {
    init_lr: LearningRate,
    step_size: usize,
    gamma: f64,
    // The index of the current iteration.
    // `i32` is used for avoiding truncating the exponent when taking powers of `gamma`.
    iter_idx: i32,
}

impl LrScheduler for StepLrScheduler {
    fn step(&mut self) -> LearningRate {
        self.iter_idx = self
            .iter_idx
            .checked_add(1)
            .expect("`.step()` should be called no more than `i32::MAX + 1` times");
        // Type casting below causes no truncation, as all the values fall within the ranges.
        self.init_lr
            * self
                .gamma
                .powi((self.iter_idx as usize / self.step_size) as i32)
    }

    fn to_record(&self) -> LrSchedulerRecord {
        LrSchedulerRecord::from_state(&StepLrSchedulerState {
            iter_idx: self.iter_idx,
        })
    }

    fn load_record(&mut self, record: LrSchedulerRecord) {
        if let Some(state) = record.into_state::<StepLrSchedulerState>() {
            self.iter_idx = state.iter_idx;
        }
    }

View on GitHub (pinned to d16f7ba2ed)

Solutions

1. Practically unreachable (over 2 billion steps); ignore unless running extreme step counts
2. Reset the scheduler from its record if you must continue beyond the limit
3. Change `iter_idx` to i64 in step.rs if the workload genuinely needs it

When it happens

Trigger: Thrown at crates/burn-optim/src/lr_scheduler/step.rs:92 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of tracel-ai/burn@d16f7ba2ed (2026-09-05). Data as JSON: /api/errors/4e9bdaa49e64534f. Report an issue: GitHub.