{"record":{"id":"e73f089e6fa04712","repo":"Hmbown/CodeWhale","slug":"codewhale-home-directory-not-found","errorCode":null,"errorMessage":"Codewhale home directory not found","messagePattern":"Codewhale home directory not found","errorType":"exception","errorClass":"std::io::Error","httpStatus":null,"severity":"error","filePath":"crates/tui/src/tui/onboarding/mod.rs","lineNumber":276,"sourceCode":"    if primary.exists() {\n        return primary;\n    }\n    if let Some(legacy_home) = legacy_home {\n        let legacy = legacy_home.join(ONBOARDED_MARKER_FILE);\n        if legacy.exists() {\n            return legacy;\n        }\n    }\n    primary\n}\n\npub fn is_onboarded() -> bool {\n    default_marker_path().is_some_and(|path| path.exists())\n}\n\npub fn mark_onboarded() -> std::io::Result<PathBuf> {\n    let path = default_marker_path().ok_or_else(|| {\n        std::io::Error::new(\n            std::io::ErrorKind::NotFound,\n            \"Codewhale home directory not found\",\n        )\n    })?;\n    mark_onboarded_at_path(path)\n}\n\n#[cfg(test)]\nfn mark_onboarded_at_home(home: &Path) -> std::io::Result<PathBuf> {\n    let path = marker_path_with_home(home);\n    mark_onboarded_at_path(path)\n}\n\nfn mark_onboarded_at_path(path: PathBuf) -> std::io::Result<PathBuf> {\n    if let Some(parent) = path.parent() {\n        std::fs::create_dir_all(parent)?;\n    }\n    std::fs::write(&path, \"\")?;","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/0c42157ee52f9d55af2b506d71b46249910f77d3/crates/tui/src/tui/onboarding/mod.rs#L258-L294","documentation":"NotFound ('Codewhale home directory not found') returned by mark_onboarded when default_marker_path() is None. The marker path is derived from codewhale_config::codewhale_home(), which errors when the Codewhale home cannot be resolved — classically because the process has no usable HOME (or configured equivalent). Without a home there is nowhere to write the onboarding marker, so the call fails before any I/O.","triggerScenarios":"Completing onboarding in a process whose environment lacks HOME (service/daemon, stripped container, some CI runners, double-forked launchers), or where the configured Codewhale home root cannot be resolved at all.","commonSituations":"Running the TUI under systemd/cron/IDE services with a sanitized env; Docker/Podman images with no HOME set; launchd plists without EnvironmentVariables; misconfigured CODEWHALE/XDG home variables pointing somewhere unresolvable.","solutions":["Set HOME to a writable directory for the process (export HOME=/home/user or the service equivalent)","If you use an explicit Codewhale home setting, verify it points to a creatable directory","For containers, add ENV HOME=/root (or a dedicated user) to the image"],"exampleFix":"# before\n[Service]\nExecStart=/usr/bin/codewhale   # no HOME -> mark_onboarded fails NotFound\n\n# after\n[Service]\nEnvironment=\"HOME=/var/lib/codewhale\"\nExecStart=/usr/bin/codewhale","handlingStrategy":"validation","validationCode":"// Verify a home is resolvable before starting the onboarding flow.\nif std::env::var_os(\"HOME\").map_or(true, |h| h.is_empty()) {\n    return Err(fatal(\"HOME is not set; cannot store Codewhale state\"));\n}\nif codewhale_config::codewhale_home().is_err() {\n    return Err(fatal(\"Codewhale home unresolvable; check HOME / config\"));\n}","typeGuard":"fn is_missing_home(e: &std::io::Error) -> bool {\n    e.kind() == std::io::ErrorKind::NotFound && e.to_string().contains(\"home directory not found\")\n}","tryCatchPattern":"match mark_onboarded() {\n    Ok(p) => Ok(p),\n    Err(e) if is_missing_home(&e) => Err(hint(\"set HOME (or Codewhale home config) and relaunch\")),\n    Err(e) => Err(e),\n}","preventionTips":["Set an explicit HOME in service/launcher definitions and Dockerfiles","Fail fast at startup when the state directory cannot be resolved, before onboarding begins","Keep an explicit Codewhale home setting in managed deployments instead of relying on inherited env"],"tags":["onboarding","home-directory","environment","config","rust"],"backgroundTag":"missing-home-directory","analyzedSha":"0c42157ee52f9d55af2b506d71b46249910f77d3","analyzedAt":"2026-08-20T21:50:45.477Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}