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

failed to find os config dir.

Error message

failed to find os config dir.

What it means

get_app_config_path() resolves gitui's config directory: dirs::config_dir() on all platforms except macOS, where gitui deliberately uses home_dir()/.config. The lookup returns None when the home directory cannot be determined (Linux: HOME unset and XDG_CONFIG_HOME unusable; macOS: HOME unset) or when XDG_CONFIG_HOME is set to a non-absolute path, which the dirs crate rejects. Because theme and key config live under this path, the anyhow error aborts startup.

Source

Thrown at src/args.rs:235

		.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."))?;

	path.push("gitui");
	Ok(path)
}

#[test]
fn verify_app() {
	app().debug_assert();
}

View on GitHub (pinned to 2fa693cb6e)

Solutions

1. Set HOME to an absolute path in the launching environment (export HOME=/home/<user>).
2. Set XDG_CONFIG_HOME to an absolute path (export XDG_CONFIG_HOME=$HOME/.config) on Linux.
3. On macOS, ensure HOME is exported in launchd agents and shells alike.
4. For programmatic use, fall back to a bundled/default config when dirs::config_dir() is None rather than failing.

Example fix

# before
env -i /usr/bin/gitui   # bails: failed to find os config dir.
# after
env -i HOME=$HOME /usr/bin/gitui

// Rust: tolerate a missing config dir
// before
let cfg = get_app_config_path()?;
// after
let cfg = get_app_config_path().unwrap_or_else(|_| std::env::temp_dir().join("gitui"));

# shell
[ -n "$HOME" ] && [ "${XDG_CONFIG_HOME:-""}" = "${XDG_CONFIG_HOME#/}" ] && echo 'XDG_CONFIG_HOME looks relative'

// Rust
dirs::config_dir().is_some()

When it happens

Trigger: Running gitui with HOME unset/empty in cron, systemd, docker, or su contexts; exporting XDG_CONFIG_HOME with a relative path like .config; macOS with an unset HOME in a launchd agent.

Common situations: Service definitions and CI runners that spawn TUI tools without login environments; hardened containers; dotfiles that export relative XDG paths; ssh sessions into accounts with broken passwd entries.

Related errors

• failed to find os cache dir.
• failed to find the home directory
• editor env variable found empty: {}

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