{"record":{"id":"c12214e54938ba0c","repo":"gitui-org/gitui","slug":"failed-to-find-os-cache-dir","errorCode":null,"errorMessage":"failed to find os cache dir.","messagePattern":"failed to find os cache dir\\.","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src/args.rs","lineNumber":217,"sourceCode":"\t\tlet mut path = get_app_cache_path()?;\n\t\tpath.push(\"gitui.log\");\n\t\tpath\n\t};\n\n\tprintln!(\"Logging enabled. Log written to: {}\", path.display());\n\n\tWriteLogger::init(\n\t\tLevelFilter::Trace,\n\t\tConfig::default(),\n\t\tFile::create(path)?,\n\t)?;\n\n\tOk(())\n}\n\nfn get_app_cache_path() -> Result<PathBuf> {\n\tlet mut path = dirs::cache_dir()\n\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.\"))?;","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/gitui-org/gitui/blob/2fa693cb6ed431b21ebc300dd02e83c2476699ce/src/args.rs#L199-L235","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","On Linux set XDG_CACHE_HOME to an absolute path (export XDG_CACHE_HOME=$HOME/.cache) - relative values are ignored by the dirs crate.","For containers/schedulers, pass the environment through explicitly or use an entrypoint that establishes HOME and USER.","If embedding this code path, probe dirs::cache_dir() first and skip file logging when it is None instead of propagating the error."],"exampleFix":"# launcher / unit file\n# before: gitui exits with 'failed to find os cache dir.'\n[Service]\nEnvironment=\n# after\n[Service]\nEnvironment=HOME=/home/user\n\n// Rust callers: probe before wiring the logger\n// before\nlet p = get_app_cache_path()?;\n// after\nif let Some(mut p) = dirs::cache_dir() {\n    p.push(\"gitui\");\n    // init logger, fall back to no logging on failure\n}","handlingStrategy":"validation","validationCode":"# shell\n[ -n \"$HOME\" ] || echo \"gitui will fail: HOME unset\"\n\n// Rust: probe before initializing gitui's logging path\ndirs::cache_dir().is_some()\n// stricter unix probe:\nstd::env::var_os(\"HOME\").filter(|h| !h.is_empty()).is_some()","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set HOME (and absolute XDG_CACHE_HOME/XDG_CONFIG_HOME) in systemd units, cron entries, and container entrypoints that launch TUI tools.","Test launches with env -i to catch environment assumptions early.","Never set XDG_* variables to relative paths - the dirs crate silently ignores them."],"tags":["environment","dirs","home-dir","xdg","startup","logger"],"backgroundTag":"missing-home-env-var","analyzedSha":"2fa693cb6ed431b21ebc300dd02e83c2476699ce","analyzedAt":"2026-08-16T23:07:36.562Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}