sxyazi/yazi · error

chafa failed with status: {}

Error message

chafa failed with status: {}

What it means

The chafa preview adapter shells out to the `chafa` binary to render image previews. If the spawned process exits with a non-zero status, the adapter surfaces the exit status as an anyhow error instead of a preview. This is a wrapper around the external tool's failure, not a yazi-internal fault.

Source

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

				"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,
		};

		ADAPTOR.image_hide()?;
		ADAPTOR.shown_store(area);

View on GitHub (pinned to 5f901b886b)

Solutions

1. Install or update chafa (`apt install chafa`, `brew install chafa`) and verify `chafa --version` works
2. Run the exact chafa command manually with the same flags to see chafa's own error message
3. Check that the image file exists and is readable by the chafa process
4. Review yazi adapter config for invalid options forwarded to chafa; remove unsupported flags

Example fix

// before
# yazi.toml
[preview]
image_filter = "invalid-flag-value"  # forwarded to chafa, exits non-zero
// after
[preview]
image_filter = "triangle"  # valid value accepted by chafa

use std::process::Command;
fn chafa_available() -> bool {
    Command::new("chafa").arg("--version").output()
        .map(|o| o.status.success()).unwrap_or(false)
}

match adapter.show(path).await {
    Err(e) if e.to_string().starts_with("chafa failed with status") => {
        tracing::warn!("image preview unavailable: {e:#}");
        fallback_to_text_preview(path).await;
    }
    other => other?,
}

When it happens

Trigger: `image_show` spawns `chafa` with the image path and options; `wait_with_output()` returns a non-successful `ExitStatus` — e.g. chafa can't read the input file, unsupported format, bad flags, or a chafa version whose CLI changed.

Common situations: `chafa` not installed or an old/newer version with different CLI flags; previewing a corrupt or unsupported image file; permission problems on the image path; misconfigured adapter options in yazi's `[preview]` config passed through to chafa.

Related errors

• unknown option: {}
• unknown task: {}
• failed to spawn chafa: {e}
• --target must be valid UTF-8
• --bin-dir is only valid for the install task

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