{"record":{"id":"b0c1b7ef406eb977","repo":"gitui-org/gitui","slug":"failed-to-find-os-config-dir","errorCode":null,"errorMessage":"failed to find os config dir.","messagePattern":"failed to find os config dir\\.","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src/args.rs","lineNumber":235,"sourceCode":"\t\t.ok_or_else(|| anyhow!(\"failed to find os cache dir.\"))?;\n\n\tpath.push(\"gitui\");\n\tfs::create_dir_all(&path).with_context(|| {\n\t\tformat!(\n\t\t\t\"failed to create cache directory: {}\",\n\t\t\tpath.display()\n\t\t)\n\t})?;\n\tOk(path)\n}\n\npub fn get_app_config_path() -> Result<PathBuf> {\n\tlet mut path = if cfg!(target_os = \"macos\") {\n\t\tdirs::home_dir().map(|h| h.join(\".config\"))\n\t} else {\n\t\tdirs::config_dir()\n\t}\n\t.ok_or_else(|| anyhow!(\"failed to find os config dir.\"))?;\n\n\tpath.push(\"gitui\");\n\tOk(path)\n}\n\n#[test]\nfn verify_app() {\n\tapp().debug_assert();\n}\n","sourceCodeStart":217,"sourceCodeEnd":245,"githubUrl":"https://github.com/gitui-org/gitui/blob/2fa693cb6ed431b21ebc300dd02e83c2476699ce/src/args.rs#L217-L245","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set HOME to an absolute path in the launching environment (export HOME=/home/<user>).","Set XDG_CONFIG_HOME to an absolute path (export XDG_CONFIG_HOME=$HOME/.config) on Linux.","On macOS, ensure HOME is exported in launchd agents and shells alike.","For programmatic use, fall back to a bundled/default config when dirs::config_dir() is None rather than failing."],"exampleFix":"# before\nenv -i /usr/bin/gitui   # bails: failed to find os config dir.\n# after\nenv -i HOME=$HOME /usr/bin/gitui\n\n// Rust: tolerate a missing config dir\n// before\nlet cfg = get_app_config_path()?;\n// after\nlet cfg = get_app_config_path().unwrap_or_else(|_| std::env::temp_dir().join(\"gitui\"));","handlingStrategy":"validation","validationCode":"# shell\n[ -n \"$HOME\" ] && [ \"${XDG_CONFIG_HOME:-\"\"}\" = \"${XDG_CONFIG_HOME#/}\" ] && echo 'XDG_CONFIG_HOME looks relative'\n\n// Rust\ndirs::config_dir().is_some()","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set HOME explicitly in every launcher that is not a login shell.","Keep XDG_CONFIG_HOME absolute or unset.","On macOS remember gitui uses ~/.config directly - HOME matters even without XDG."],"tags":["environment","dirs","home-dir","xdg","configuration","startup"],"backgroundTag":"missing-home-env-var","analyzedSha":"2fa693cb6ed431b21ebc300dd02e83c2476699ce","analyzedAt":"2026-08-16T23:07:36.562Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}