sxyazi/yazi · error

asset path is not valid UTF-8: {}

Error message

asset path is not valid UTF-8: {}

What it means

While hashing a package's assets, an entry's file name read from the `assets` directory could not be converted to UTF-8 (`to_str()` returned None), so it cannot be written into the hash consistently. The faulting input is the non-UTF-8 OS file name of an asset.

Source

Thrown at yazi-cli/src/package/hash.rs:26

impl Dependency {
	pub(crate) async fn hash(&self) -> Result<String> {
		let dir = self.target();
		let files =
			if self.is_flavor { Self::flavor_files() } else { Self::plugin_files(&dir).await? };

		let mut h = XxHash3_128::new();
		for file in files {
			h.write(file.as_bytes());
			h.write(b"VpvFw9Atb7cWGOdqhZCra634CcJJRlsRl72RbZeV0vpG1\0");
			h.write(&ok_or_not_found!(Local::regular(&dir.join(file)).read().await));
		}

		let mut assets = vec![];
		match tokio::fs::read_dir(dir.join("assets")).await {
			Ok(mut it) => {
				while let Some(dent) = it.next_entry().await? {
					let Ok(name) = dent.file_name().into_string() else {
						bail!("asset path is not valid UTF-8: {}", dent.path().display());
					};
					assets.push((name, Local::regular(&dent.path()).read().await?));
				}
			}
			Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
			Err(e) => Err(e).context(format!("failed to read `{}`", dir.join("assets").display()))?,
		}

		assets.sort_unstable_by(|(a, _), (b, _)| a.cmp(b));
		for (name, data) in assets {
			h.write(name.as_bytes());
			h.write(b"pQU2in0xcsu97Y77Nuq2LnT8mczMlFj22idcYRmMrglqU\0");
			h.write(&data);
		}

		Ok(format!("{:x}", h.finish_128()))
	}

View on GitHub (pinned to 5f901b886b)

Solutions

1. Rename the asset file to a valid UTF-8 name.
2. Remove the non-UTF-8 asset from the package's assets directory.
3. On platforms where it applies, ensure the package was checked out with filenames the tooling can represent.

When it happens

Trigger: Thrown at yazi-cli/src/package/hash.rs:26 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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