sxyazi/yazi · critical

Failed to get cache directory

Error message

Failed to get cache directory

What it means

Yazi's XDG helper caches the cache directory on first use via OnceLock; on Windows it calls dirs::cache_dir() and panics via expect() if the OS returns None. dirs::cache_dir() returns None when it cannot resolve the user profile (missing USERPROFILE/APPDATA environment variables). This is a hard panic, not a recoverable Result, because yazi cannot run without a cache location.

Solutions

1. Ensure USERPROFILE and APPDATA (or HOME) environment variables are set to an absolute path before launching yazi
2. If launched from a service/SSH, run under an interactive user session or export the vars manually in the wrapper script
3. Check the Windows user profile exists and the registry ProfileImagePath points to a valid directory

Example fix

// before (broken launch wrapper)
start yazi.exe
// after
set "USERPROFILE=%SystemDrive%\Users\alice"
set "APPDATA=%USERPROFILE%\AppData\Roaming"
yazi.exe

if !process::Command::new("cmd").args(["/C","echo %APPDATA%"]).status().is_ok() || env::var_os("APPDATA").is_none() { eprintln!("APPDATA/USERPROFILE missing; yazi cache dir unavailable"); }

When it happens

Trigger: Calling yazi_fs::xdg cache_dir accessor on Windows when dirs::cache_dir() returns None, i.e. the %USERPROFILE% or %APPDATA% env vars are unset or invalid at process startup.

Common situations: Running `ya`/`yazi` from a stripped environment (services, SSH with env clearing, runas accounts, CI containers on Windows) where the user profile env vars are missing; corrupted user registry profile paths.

Related errors

• Failed to get asset directory
• Failed to get state directory
• Failed to get config directory
• Unwinding must be enabled for Windows. Please use `cargo…
• Due to Cargo's limitations, Yazi on crates.io must be built…

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

Appendix: source

Thrown at yazi-fs/src/xdg.rs:51

		{
			env::var_os("XDG_CONFIG_HOME")
				.map(PathBuf::from)
				.filter(|p| p.is_absolute())
				.map(|p| p.join("yazi"))
				.or_else(|| dirs::home_dir().map(|h| h.join(".config/yazi")))
				.expect("Failed to get config directory")
		}
	}

	pub fn cache_dir() -> &'static PathBuf {
		static ONCE: OnceLock<PathBuf> = OnceLock::new();
		ONCE.get_or_init(Self::load_cache_dir)
	}

	fn load_cache_dir() -> PathBuf {
		#[cfg(windows)]
		{
			dirs::cache_dir().map(|p| p.join("yazi")).expect("Failed to get cache directory")
		}
		#[cfg(unix)]
		{
			env::var_os("XDG_CACHE_HOME")
				.map(PathBuf::from)
				.filter(|p| p.is_absolute())
				.map(|p| p.join("yazi"))
				.or_else(|| dirs::home_dir().map(|h| h.join(".cache/yazi")))
				.expect("Failed to get cache directory")
		}
	}

	pub fn state_dir() -> &'static PathBuf {
		static ONCE: OnceLock<PathBuf> = OnceLock::new();
		ONCE.get_or_init(Self::load_state_dir)
	}

	fn load_state_dir() -> PathBuf {

View on GitHub (pinned to 5f901b886b)