sxyazi/yazi · error

uninitialized ueberzugpp

Error message

uninitialized ueberzugpp

What it means

The ueberzugpp daemon channel (`DEMON`) was never initialized when `image_show` was called, meaning the background task holding the child process and its sender was not started. The guard is a `let-else` on the global `DEMON` slot; the fault is calling show before the driver's init ran (or after it failed).

Source

Thrown at yazi-adapter/src/drivers/ueberzug.rs:49

			while let Some(cmd) = rx.recv().await {
				let exit = child.as_mut().and_then(|c| c.try_wait().ok());
				if exit != Some(None) {
					child = None;
				}
				if child.is_none() {
					child = Self::create_demon(driver).ok();
				}
				if let Some(c) = &mut child {
					Self::send_command(driver, c, cmd).await.ok();
				}
			}
		});
		DEMON.init(Some(tx))
	}

	pub(super) async fn image_show(path: PathBuf, max: Rect) -> Result<Rect> {
		let Some(tx) = &*DEMON else {
			bail!("uninitialized ueberzugpp");
		};

		let (w, h, path) = tokio::task::spawn_blocking(move || {
			ImageReader::open(&path)?.with_guessed_format()?.into_dimensions().map(|(w, h)| (w, h, path))
		})
		.await??;

		let area = Dimension::cell_size()
			.map(|(cw, ch)| Rect {
				x:      max.x,
				y:      max.y,
				width:  max.width.min((w.min(YAZI.preview.max_width as _) as f64 / cw).ceil() as _),
				height: max.height.min((h.min(YAZI.preview.max_height as _) as f64 / ch).ceil() as _),
			})
			.unwrap_or(max);

		tx.send(Some((path, area)))?;
		ADAPTOR.shown_store(area);

View on GitHub (pinned to 5f901b886b)

Solutions

1. Ensure ueberzug is enabled in the adapter layer before showing images.
2. Check that ueberzugpp is installed and the daemon task spawned successfully at startup.
3. Fall back to another preview adapter when the daemon is unavailable.

When it happens

Trigger: Thrown at yazi-adapter/src/drivers/ueberzug.rs:49 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/28df917ca0715498. Report an issue: GitHub.