gitui-org/gitui · error · anyhow::Error

failed to find os cache dir.

Error message

failed to find os cache dir.

What it means

gitui resolves the OS cache directory via the dirs crate (dirs::cache_dir()) to place its log file: setup_logging() calls get_app_cache_path(), appends gitui/gitui.log, and initializes a simplelog WriteLogger there. The dirs crate returns None when the platform lookup fails - on Linux when neither XDG_CACHE_HOME (absolute paths only) nor HOME is resolvable, on macOS when the home directory cannot be determined, on Windows when the LocalAppData known folder is unavailable. When the Option is None this anyhow error aborts startup.

Source

Thrown at src/args.rs:217

		let mut path = get_app_cache_path()?;
		path.push("gitui.log");
		path
	};

	println!("Logging enabled. Log written to: {}", path.display());

	WriteLogger::init(
		LevelFilter::Trace,
		Config::default(),
		File::create(path)?,
	)?;

	Ok(())
}

fn get_app_cache_path() -> Result<PathBuf> {
	let mut path = dirs::cache_dir()
		.ok_or_else(|| anyhow!("failed to find os cache dir."))?;

	path.push("gitui");
	fs::create_dir_all(&path).with_context(|| {
		format!(
			"failed to create cache directory: {}",
			path.display()
		)
	})?;
	Ok(path)
}

pub fn get_app_config_path() -> Result<PathBuf> {
	let mut path = if cfg!(target_os = "macos") {
		dirs::home_dir().map(|h| h.join(".config"))
	} else {
		dirs::config_dir()
	}
	.ok_or_else(|| anyhow!("failed to find os config dir."))?;

View on GitHub (pinned to 2fa693cb6e)

Solutions

1. Set HOME to an absolute path in whatever launches gitui (export HOME=/home/<user>, or an Environment=HOME=/home/user directive in the systemd unit, or -e HOME in docker run).
2. On Linux set XDG_CACHE_HOME to an absolute path (export XDG_CACHE_HOME=$HOME/.cache) - relative values are ignored by the dirs crate.
3. For containers/schedulers, pass the environment through explicitly or use an entrypoint that establishes HOME and USER.
4. If embedding this code path, probe dirs::cache_dir() first and skip file logging when it is None instead of propagating the error.

Example fix

# launcher / unit file
# before: gitui exits with 'failed to find os cache dir.'
[Service]
Environment=
# after
[Service]
Environment=HOME=/home/user

// Rust callers: probe before wiring the logger
// before
let p = get_app_cache_path()?;
// after
if let Some(mut p) = dirs::cache_dir() {
    p.push("gitui");
    // init logger, fall back to no logging on failure
}

# shell
[ -n "$HOME" ] || echo "gitui will fail: HOME unset"

// Rust: probe before initializing gitui's logging path
dirs::cache_dir().is_some()
// stricter unix probe:
std::env::var_os("HOME").filter(|h| !h.is_empty()).is_some()

When it happens

Trigger: Launching gitui with HOME unset or empty (cron entry, systemd unit, docker exec with a scrubbed environment, su to a user without a passwd entry); setting XDG_CACHE_HOME to a relative path, which dirs ignores, leaving no fallback when HOME is also missing; running under env -i.

Common situations: gitui launched from a service manager or CI runner without a login environment; OCI containers that drop HOME; users overriding XDG_* variables with relative values in shell rc files; chroot/minimal images missing the user database.

Related errors

• failed to find os config dir.
• failed to find the home directory

AI-assisted analysis of gitui-org/gitui@2fa693cb6e (2026-08-16). Data as JSON: /api/errors/c12214e54938ba0c. Report an issue: GitHub.