sxyazi/yazi · error · anyhow::Error

failed to spawn chafa: {e}

Error message

failed to spawn chafa: {e}

What it means

The Chafa image driver renders images as terminal symbols by spawning the external `chafa` process via tokio::process::Command. If spawn fails — most commonly NotFound because chafa is not installed or not on the PATH yazi inherited — the io error is wrapped as "failed to spawn chafa: {e}" and image preview for that file aborts.

Source

Thrown at yazi-adapter/src/drivers/chafa.rs:40

				"off",
				"--probe",
				"off",
				"--polite",
				"on",
				"--passthrough",
				"none",
				"--animate",
				"off",
				"--view-size",
			])
			.arg(format!("{}x{}", max.width, max.height))
			.arg(path)
			.stdin(Stdio::null())
			.stdout(Stdio::piped())
			.stderr(Stdio::null())
			.kill_on_drop(true)
			.spawn()
			.map_err(|e| anyhow!("failed to spawn chafa: {e}"))?;

		let output = child.wait_with_output().await?;
		if !output.status.success() {
			bail!("chafa failed with status: {}", output.status);
		} else if output.stdout.is_empty() {
			bail!("chafa returned no output");
		}

		let lines: Vec<_> = output.stdout.split(|&b| b == b'\n').collect();
		let Ok(Some(first)) = lines[0].to_text().map(|mut t| t.lines.pop()) else {
			bail!("failed to parse chafa output");
		};

		let area = Rect {
			x:      max.x,
			y:      max.y,
			width:  first.width() as u16,
			height: lines.len() as u16,

View on GitHub (pinned to 94abcfa92f)

Solutions

1. Install chafa (e.g. `sudo apt install chafa` / `brew install chafa`) and confirm `chafa --version` runs in the same shell that launches yazi
2. Verify PATH from inside yazi (e.g. `:sh which chafa`) and launch yazi from an environment whose PATH includes the binary
3. If chafa cannot be provided, rely on a different image adaptor for that terminal

// Before rendering with the chafa driver:
if which::which("chafa").is_err() {
    bail!("chafa is not installed or not on PATH; install it or use another adaptor");
}

match Chafa::image_show(path, area).await {
    Ok(rect) => { /* render */ }
    Err(e) if e.to_string().contains("failed to spawn chafa") => { /* fall back to another adaptor / placeholder */ }
    Err(e) => return Err(e),
}

When it happens

Trigger: Selecting the chafa adaptor (or falling back to it) on a host where the chafa binary is missing, not executable, or unreachable due to a restricted PATH; spawn can also fail under resource exhaustion (fork/EAGAIN).

Common situations: Fresh systems without chafa installed; SSH sessions with minimal PATH; snap/flatpak-installed chafa not visible on PATH; themes/configs expecting symbol-based previews.

Related errors

• failed to get current working directory
• Failed to get config directory
• Failed to get cache directory
• Failed to get state directory
• Time went backwards

AI-assisted analysis of sxyazi/yazi@94abcfa92f (2026-08-16). Data as JSON: /api/errors/badefb8d33122744. Report an issue: GitHub.