tracel-ai/burn · error

Can load model checkpoint.

Error message

Can load model checkpoint.

What it means

`Learner::load_checkpoint` restores the model record for a given epoch via the model checkpointer's `restore(epoch)` and unwraps it with expect(). If no model checkpoint exists for that epoch or the file cannot be read/deserialized, the process panics with this message.

Source

Thrown at crates/burn-train/src/learner/base.rs:200

                    self.lr_scheduler
                        .save(epoch, learner.lr_scheduler.to_record())
                        .expect("Can save learning rate scheduler checkpoint.");
                }
            }
        }
    }

    /// Load a training checkpoint.
    ///
    /// No device is taken: checkpoints are device-free burnpack records (file-backed bytes). On
    /// load, the model keeps the device of the learner's existing parameters, and the optimizer
    /// state is migrated to each parameter's device on the next step. The training device is fixed
    /// earlier, when the learner's model is created/forked.
    pub fn load_checkpoint(&self, mut learner: Learner<M>, epoch: usize) -> Learner<M> {
        let record = self
            .model
            .restore(epoch)
            .expect("Can load model checkpoint.");
        learner.load_model(record);

        let record = self
            .optim
            .restore(epoch)
            .expect("Can load optimizer checkpoint.");
        learner.load_optim(record);

        let record = self
            .lr_scheduler
            .restore(epoch)
            .expect("Can load learning rate scheduler checkpoint.");
        learner.load_scheduler(record);

        learner
    }
}

View on GitHub (pinned to d16f7ba2ed)

Solutions

1. Confirm a checkpoint for that exact epoch exists in the directory (list files) and use the highest saved epoch otherwise.
2. Check the checkpoint wasn't pruned by keepN/keepOld settings; keep the needed epoch or use an existing one.
3. Ensure the model architecture and burn crate version match the ones used at save time; retrain or regenerate the checkpoint if they changed.
4. Use the same recorder settings (path prefix, format) as the saving run.
5. If the file is corrupt, restore from backup or fall back to another epoch.

Example fix

// before
learner::load_checkpoint(learner, 20); // only epochs 15..=19 were kept
// after
let epoch = latest_saved_epoch(&checkpoint_dir); // scan dir for saved epochs
learner::load_checkpoint(learner, epoch);

fn saved_epochs(dir: &str, prefix: &str) -> Vec<usize> {
    std::fs::read_dir(dir).unwrap()
        .filter_map(|e| e.ok().file_name().into_string().ok())
        .filter_map(|n| n.strip_prefix(prefix)?.split('-').next()?.parse().ok())
        .collect()
}
let epochs = saved_epochs(&checkpoint_dir, "model");
assert!(epochs.contains(&epoch), "epoch {epoch} not checkpointed; available: {epochs:?}");

fn epoch_checkpoints_exist(dir: &str, epoch: usize) -> bool {
    ["model", "optim", "scheduler"].iter().all(|p| Path::new(dir).join(format!("{p}-{epoch}")).exists())
}

let result = std::panic::catch_unwind(AssertUnwindSafe(|| learner::load_checkpoint(learner, epoch)));
match result {
    Ok(l) => l,
    Err(_) => { eprintln!("resume failed for epoch {epoch}; falling back to latest"); learner }
}

When it happens

Trigger: Calling load_checkpoint(learner, epoch) when the model checkpoint file for `epoch` was never saved (wrong epoch number, training crashed before that epoch) or cannot be deserialized (architecture changed, different burn version/recorder format, corrupted file).

Common situations: Resuming from an epoch that wasn't checkpointed (e.g. keepN deleted it); switching model structure or tensor backend between save and load; loading checkpoints written by an older burn version; path mismatch between the saving and resuming jobs.

Related errors

• Can load optimizer checkpoint.
• Optimizer record tensors should carry a parameter id.
• Can load learning rate scheduler checkpoint.
• deserialize_any is not implemented
• deserialize_i8 is not implemented

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