tracel-ai/burn · error · std::io::Error

NotFound

NotFound

Error message

Storage key '{}' not found in TAR archive

What it means

`TarSource::read_file` looks up the storage key (numeric suffix of paths like `data/0`) in the storage map built at construction, and also bounds-checks offset+size against the storages blob. If the key is missing or the recorded range exceeds the blob, it raises NotFound, meaning the requested storage cannot be served from this TAR archive.

Source

Thrown at crates/burn-store/src/pytorch/lazy_data.rs:386

        Ok(Self {
            storage_map,
            storages_data,
        })
    }

    /// Read data for a specific storage key
    pub fn read_file(&self, key: &str) -> std::io::Result<Vec<u8>> {
        // Extract the storage key from paths like "data/0"
        let storage_key = key.split('/').next_back().unwrap_or(key);

        if let Some(&(offset, size)) = self.storage_map.get(storage_key)
            && offset + size <= self.storages_data.len()
        {
            return Ok(self.storages_data[offset..offset + size].to_vec());
        }

        Err(std::io::Error::new(
            std::io::ErrorKind::NotFound,
            format!("Storage key '{}' not found in TAR archive", storage_key),
        ))
    }

    /// Read a range of data for a specific storage key (avoids double allocation)
    pub fn read_file_range(
        &self,
        key: &str,
        offset: usize,
        length: usize,
    ) -> std::io::Result<Vec<u8>> {
        let storage_key = key.split('/').next_back().unwrap_or(key);

        if let Some(&(storage_offset, storage_size)) = self.storage_map.get(storage_key)
            && storage_offset + storage_size <= self.storages_data.len()
        {
            let start = storage_offset + offset;

View on GitHub (pinned to d16f7ba2ed)

Solutions

  1. Confirm the key exists by listing the archive's tensor/record keys before reading
  2. Re-download or re-export the checkpoint — truncation is the most common cause
  3. Check the file loads eagerly (non-lazy) to distinguish a key problem from a mapping problem
  4. Verify the key path format; only the final `/`-separated segment is used, so pass the full storage path as the reader provides it

Example fix

// before
let bytes = tar_source.read_file("data/99")?; // NotFound
// after
let keys: Vec<_> = tar_source.storage_keys().collect();
assert!(keys.contains(&"99"), "storage 99 missing; available: {keys:?}");
let bytes = tar_source.read_file("data/99")?;
Defensive patterns

Strategy: try-catch

Validate before calling

fn storage_available(src: &TarSource, key: &str) -> bool {
    let storage_key = key.split('/').next_back().unwrap_or(key);
    src.contains_key(storage_key)
}

Try / catch

match tar_source.read_file(key) {
    Ok(bytes) => bytes,
    Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
        return Err(anyhow::anyhow!(
            "storage {key} missing from archive; file may be truncated — re-download and retry"
        ));
    }
    Err(e) => return Err(e.into()),
}

Prevention

When it happens

Trigger: Calling `TarSource::read_file("data/N")` (or read_file_range) where N was never recorded during `new` — key not in the storages pickle, parsing stopped early (count pickle read as 0 or a truncated blob), or the blob is shorter than offset+size for that key.

Common situations: Requesting a tensor index that doesn't exist in the checkpoint; a truncated download of a .pth file so later storages were never mapped; a storages count pickle that failed to parse leaving the map empty; key-path format mismatches after suffix extraction.

Understand the failure class

Background: "Not Found" / HTTP 404 Errors: What They Mean and How to Fix Them Across Libraries — this error's family across 6 libraries.

Related errors

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