sxyazi/yazi · error · io::Error

Cannot parse cache stamp: {e}

Error message

Cannot parse cache stamp: {e}

What it means

This io::Error is produced when Stamp::try_from(Vec<u8>) fails to parse the bytes read from the cache stamp file; the inner parse error is embedded as 'Cannot parse cache stamp: {e}'. The stamp data was readable but not a valid stamp structure.

Source

Thrown at yazi-vfs/src/stamp.rs:28

	pub async fn read<U>(url: U) -> io::Result<Self>
	where
		U: AsUrl,
	{
		let path =
			url.as_url().stamp_entry().ok_or_else(|| io::Error::other("Cannot determine cache stamp"))?;

		Self::read_at(&path).await
	}

	async fn read_at(path: &Path) -> io::Result<Self> {
		let data = Local::regular(path)
			.read()
			.await
			.map_err(|e| io::Error::new(e.kind(), format!("Cannot read cache stamp: {e}")))?;

		Self::try_from(data)
			.map_err(|e| io::Error::new(e.kind(), format!("Cannot parse cache stamp: {e}")))
	}

	pub async fn resolve<U, S>(dir: U, key: S) -> io::Result<UrlBuf>
	where
		U: AsUrl,
		S: AsStrand,
	{
		let dir = dir.as_url();
		let key = key.as_strand();

		let mut path =
			dir.auth().stamp_root().ok_or_else(|| io::Error::other("Cannot determine stamp root"))?;
		path.push(key.as_os()?);

		let stamp = Self::read_at(&path).await?;
		let name = StrandCow::with(dir.loc().kind(), stamp.name()).map_err(io::Error::other)?;

		let url = dir.try_join(name)?;

View on GitHub (pinned to 8ebf930f17)

Solutions

1. Delete the invalid stamp file and re-create it via Stamp::write (re-download the entry)
2. Clear the Yazi cache directory to remove stale-format stamps
3. Upgrade/downgrade consistently so the stamp format version matches between writer and reader

Example fix

// before
let url = Stamp::resolve(dir, key).await?;
// after
let url = Stamp::resolve(dir, key).await
    .inspect_err(|_| let _ = std::fs::remove_file(stamp_path)) // drop corrupt stamp
    .or_else(|_| re_download().await)?;

let data = tokio::fs::read(&stamp_path).await?;
if data.len() <= Stamp::SIG_LEN { /* corrupt: drop and re-fetch */ }

fn stamp_parseable(data: &[u8]) -> bool {
    data.get(Stamp::SIG_LEN..).map(|n| !n.is_empty()).unwrap_or(false)
        && std::str::from_utf8(&data[..Stamp::SIG_LEN]).is_ok()
}

match Stamp::resolve(dir, key).await {
    Ok(url) => url,
    Err(e) if e.kind() == io::ErrorKind::InvalidData => { remove_stamp(&path); cache_miss_fallback() },
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling Stamp::read_at (via Stamp::resolve) where the file bytes do not decode into a Stamp: wrong SIG length, empty name portion, or invalid UTF-8 in the signature region.

Common situations: A truncated or corrupted stamp file (crash during write, disk full); a different Yazi version changed the stamp format; the cache file was overwritten by another program.

Related errors

• Invalid cache stamp
• {e}
• unknown error kind: {s}
• Invalid MoveOptStep data type: {value:?}
• command name cannot be empty

AI-assisted analysis of sxyazi/yazi@8ebf930f17 (2026-09-02). Data as JSON: /api/errors/d0261b7132225914. Report an issue: GitHub.