tracel-ai/burn · error

Failed to load module from file

Error message

Failed to load module from file

What it means

load_file loads a module's record from disk and applies it; the expect fires when reading or deserializing the file fails (missing file, unreadable path, or invalid/corrupt record format). It is the panicking convenience wrapper over try_load_file.

Source

Thrown at crates/burn-core/src/module/base.rs:510

    where
        Self: Sized,
    {
        self.into_record().save(path)
    }

    /// Load this module's parameters from a burnpack file on disk, returning the loaded module.
    ///
    /// Uses the default load behavior. Panics on I/O or validation errors; use
    /// [`try_load_file`](Module::try_load_file) for the fallible variant, or go through
    /// [`ModuleRecord`](crate::store::ModuleRecord) to configure dtype policy, partial loading or
    /// validation.
    #[cfg(feature = "std")]
    fn load_file<P: AsRef<std::path::Path>>(self, path: P) -> Self
    where
        Self: Sized,
    {
        self.try_load_file(path)
            .expect("Failed to load module from file")
    }

    /// Fallible variant of [`load_file`](Module::load_file).
    ///
    /// Reads the record from `path` with [`ModuleRecord::load`](crate::store::ModuleRecord::load)
    /// and applies it through [`try_load_record`](Module::try_load_record).
    #[cfg(feature = "std")]
    fn try_load_file<P: AsRef<std::path::Path>>(
        self,
        path: P,
    ) -> Result<Self, crate::store::RecordError>
    where
        Self: Sized,
    {
        let record = crate::store::ModuleRecord::load(path)?;
        self.try_load_record(record)
    }
}

View on GitHub (pinned to d16f7ba2ed)

Solutions

1. Verify the path exists and is readable before loading (std::path::Path::exists).
2. Use try_load_file and match on the Result to get the underlying io/deserialization error.
3. Re-export the checkpoint with the same burn version and recorder used at save time.

Example fix

// before
let model = Model::load_file("weights.mpk");
// after
let model = Model::try_load_file("weights.mpk")
    .unwrap_or_else(|e| panic!("failed to load weights.mpk: {e}"));

let path = std::path::Path::new("weights.mpk");
assert!(path.exists() && path.is_file(), "checkpoint file missing: {}", path.display());

let model = Model::try_load_file(&path)
    .unwrap_or_else(|e| panic!("failed to load checkpoint {}: {e}", path.display()));

When it happens

Trigger: Calling model.load_file(path) with a nonexistent path, a file saved with an incompatible recorder/format, or a truncated/corrupted checkpoint.

Common situations: Typo in checkpoint path, relative vs absolute path confusion at runtime, loading a .mpk/.bin file produced by a different burn version, or file deleted between existence check and load.

Related errors

• Can delete model checkpoint.
• Can delete optimizer checkpoint.
• Can delete learning rate scheduler checkpoint.
• Can save model checkpoint.
• Can save optimizer checkpoint.

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