What causes "Codewhale home directory not found" in Hmbown/CodeWhale?

Set HOME (or the Codewhale home env var) to a writable directory before invoking

Hmbown/CodeWhale · error · io::Error

Codewhale home directory not found

Error message

Codewhale home directory not found

What it means

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.

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

Example fix

// before
mark_onboarded()?;
// after
match mark_onboarded() {
    Ok(path) => log::info!("onboarded marker at {}", path.display()),
    Err(e) if e.kind() == io::ErrorKind::NotFound => {
        log::warn!("no Codewhale home; skipping onboarding marker");
    }
    Err(e) => return Err(e.into()),
}

Defensive patterns

Strategy: try-catch

Validate before calling

let home = std::env::var_os("HOME")
    .or_else(|| std::env::var_os("USERPROFILE"));
if home.is_none() {
    anyhow::bail!("no home directory; cannot mark onboarding");
}

Try / catch

match mark_onboarded() {
    Ok(p) => p,
    Err(e) if e.kind() == io::ErrorKind::NotFound => {
        log::warn!("Codewhale home missing; onboarding not persisted");
    }
    Err(e) => return Err(e.into()),
}

Prevention

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

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/e73f089e6fa04712. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/tui/onboarding/mod.rs:366

    if primary.exists() {
        return primary;
    }
    if let Some(legacy_home) = legacy_home {
        let legacy = legacy_home.join(ONBOARDED_MARKER_FILE);
        if legacy.exists() {
            return legacy;
        }
    }
    primary
}

pub fn is_onboarded() -> bool {
    default_marker_path().is_some_and(|path| path.exists())
}

pub fn mark_onboarded() -> std::io::Result<PathBuf> {
    let path = default_marker_path().ok_or_else(|| {
        std::io::Error::new(
            std::io::ErrorKind::NotFound,
            "Codewhale home directory not found",
        )
    })?;
    mark_onboarded_at_path(path)
}

#[cfg(test)]
fn mark_onboarded_at_home(home: &Path) -> std::io::Result<PathBuf> {
    let path = marker_path_with_home(home);
    mark_onboarded_at_path(path)
}

fn mark_onboarded_at_path(path: PathBuf) -> std::io::Result<PathBuf> {
    if let Some(parent) = path.parent() {
        std::fs::create_dir_all(parent)?;
    }
    std::fs::write(&path, "")?;

View on GitHub (pinned to 73e0f67d83)