{"record":{"id":"764f230ceb2743f3","repo":"gitui-org/gitui","slug":"failed-to-find-the-home-directory","errorCode":null,"errorMessage":"failed to find the home directory","messagePattern":"failed to find the home directory","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src/main.rs","lineNumber":329,"sourceCode":"\t\t2 => oper.recv(rx_app).map(|e| {\n\t\t\tQueueEvent::AsyncEvent(AsyncNotification::App(e))\n\t\t}),\n\t\t3 => oper.recv(rx_ticker).map(|_| QueueEvent::Notify),\n\t\t4 => oper.recv(rx_notify).map(|()| QueueEvent::Notify),\n\t\t5 => oper.recv(rx_spinner).map(|_| QueueEvent::SpinnerUpdate),\n\t\t_ => bail!(\"unknown select source\"),\n\t}?;\n\n\tOk(ev)\n}\n\nfn start_terminal(\n\tbuf: Stdout,\n\trepo_path: &RepoPath,\n) -> Result<Terminal> {\n\tlet mut path = repo_path.gitpath().canonicalize()?;\n\tlet home = dirs::home_dir().ok_or_else(|| {\n\t\tanyhow!(\"failed to find the home directory\")\n\t})?;\n\tif path.starts_with(&home) {\n\t\tlet relative_part = path\n\t\t\t.strip_prefix(&home)\n\t\t\t.expect(\"can't fail because of the if statement\");\n\t\tpath = Path::new(\"~\").join(relative_part);\n\t}\n\n\tlet mut backend = CrosstermBackend::new(buf);\n\tbackend.execute(crossterm::terminal::SetTitle(format!(\n\t\t\"gitui ({})\",\n\t\tpath.display()\n\t)))?;\n\n\tlet mut terminal = Terminal::new(backend)?;\n\tterminal.hide_cursor()?;\n\tterminal.clear()?;\n","sourceCodeStart":311,"sourceCodeEnd":347,"githubUrl":"https://github.com/gitui-org/gitui/blob/2fa693cb6ed431b21ebc300dd02e83c2476699ce/src/main.rs#L311-L347","documentation":"start_terminal() canonicalizes the repo's .git path and shortens it under ~ for the terminal window title (gitui (~/...)). dirs::home_dir() returned None: on unix, HOME is unset/empty and the passwd entry could not be used as a fallback; on Windows the user profile folder is unresolvable. Because this runs before the TUI is drawn, the anyhow error aborts startup entirely - despite only being needed for a cosmetic title.","triggerScenarios":"HOME scrubbed or empty in cron, systemd units, docker exec with a minimal env, or su to an account without a passwd entry; Windows service contexts missing USERPROFILE; env -i launches.","commonSituations":"Launching gitui from service files, CI runners, or sanitized containers; hardened images where the user database is absent or HOME is deliberately cleared.","solutions":["Export a valid HOME (export HOME=/home/user) in whatever launches gitui.","On Windows ensure USERPROFILE is set in the launching context.","Run gitui from a real login shell (bash -l) when the environment cannot be fixed at the source.","Upstream: guard the home_dir() lookup and skip the ~-shortening instead of bailing - title cosmetics are not fatal."],"exampleFix":"# before\nenv -i /usr/bin/gitui   # bails: failed to find the home directory\n# after\nenv -i HOME=$HOME /usr/bin/gitui\n\n// Rust (upstream shape): make shortening optional\nlet home = dirs::home_dir();\nif let Some(h) = home.filter(|h| path.starts_with(h)) {\n    path = Path::new(\"~\").join(path.strip_prefix(&h).unwrap());\n}","handlingStrategy":"validation","validationCode":"# shell\n[ -n \"$HOME\" ] || echo \"gitui will fail: HOME missing\"\n\n// Rust\ndirs::home_dir().is_some()","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always define HOME in unit files and containers that spawn interactive tools.","Launch TUI apps from login shells when the environment is not yours to fix.","Treat gitui's three dirs-based failures (cache/config/home) as one checklist item."],"tags":["environment","home-dir","terminal-title","startup","dirs"],"backgroundTag":"missing-home-env-var","analyzedSha":"2fa693cb6ed431b21ebc300dd02e83c2476699ce","analyzedAt":"2026-08-16T23:07:36.562Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}