{"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":"io::Error","httpStatus":null,"severity":"error","filePath":"crates/tui/src/tui/onboarding/mod.rs","lineNumber":366,"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":348,"sourceCodeEnd":384,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/src/tui/onboarding/mod.rs#L348-L384","documentation":"mark_onboarded resolves the Codewhale home directory to place the onboarding marker file. When default_marker_path() returns None — no home directory / Codewhale home can be determined — it throws NotFound with 'Codewhale home directory not found' instead of writing the marker somewhere arbitrary.","triggerScenarios":"Calling mark_onboarded in an environment where the home directory cannot be resolved (HOME unset, dirs::home_dir() None, or the configured Codewhale home path missing).","commonSituations":"Running in a systemd service, container, or CI job with no HOME; a misconfigured CODEWHALE_HOME pointing nowhere; first-run onboarding in a restricted sandbox.","solutions":["Set HOME (or the Codewhale home env var) to a writable directory before invoking","Create the configured Codewhale home directory if it is missing","Call mark_onboarded_at_path with an explicit path when the default resolution cannot be trusted","Handle NotFound and defer onboarding marking until a home is available"],"exampleFix":"// before\nmark_onboarded()?;\n// after\nmatch mark_onboarded() {\n    Ok(path) => log::info!(\"onboarded marker at {}\", path.display()),\n    Err(e) if e.kind() == io::ErrorKind::NotFound => {\n        log::warn!(\"no Codewhale home; skipping onboarding marker\");\n    }\n    Err(e) => return Err(e.into()),\n}","handlingStrategy":"try-catch","validationCode":"let home = std::env::var_os(\"HOME\")\n    .or_else(|| std::env::var_os(\"USERPROFILE\"));\nif home.is_none() {\n    anyhow::bail!(\"no home directory; cannot mark onboarding\");\n}","typeGuard":null,"tryCatchPattern":"match mark_onboarded() {\n    Ok(p) => p,\n    Err(e) if e.kind() == io::ErrorKind::NotFound => {\n        log::warn!(\"Codewhale home missing; onboarding not persisted\");\n    }\n    Err(e) => return Err(e.into()),\n}","preventionTips":["Ensure HOME/USERPROFILE is set in services, containers, and CI","Create the Codewhale home directory at startup if missing","Use mark_onboarded_at_path with an explicit path in headless contexts","Surface home-resolution failures at startup rather than at first write"],"tags":["io","not-found","home-directory","config"],"backgroundTag":"file-not-found","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}