Hmbown/CodeWhale · error · std::io::Error

Codewhale home directory not found

Error message

Codewhale home directory not found

What it means

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.

Source

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

    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 0c42157ee5)

Solutions

1. Set HOME to a writable directory for the process (export HOME=/home/user or the service equivalent)
2. If you use an explicit Codewhale home setting, verify it points to a creatable directory
3. For containers, add ENV HOME=/root (or a dedicated user) to the image

Example fix

# before
[Service]
ExecStart=/usr/bin/codewhale   # no HOME -> mark_onboarded fails NotFound

# after
[Service]
Environment="HOME=/var/lib/codewhale"
ExecStart=/usr/bin/codewhale

// Verify a home is resolvable before starting the onboarding flow.
if std::env::var_os("HOME").map_or(true, |h| h.is_empty()) {
    return Err(fatal("HOME is not set; cannot store Codewhale state"));
}
if codewhale_config::codewhale_home().is_err() {
    return Err(fatal("Codewhale home unresolvable; check HOME / config"));
}

fn is_missing_home(e: &std::io::Error) -> bool {
    e.kind() == std::io::ErrorKind::NotFound && e.to_string().contains("home directory not found")
}

match mark_onboarded() {
    Ok(p) => Ok(p),
    Err(e) if is_missing_home(&e) => Err(hint("set HOME (or Codewhale home config) and relaunch")),
    Err(e) => Err(e),
}

When it happens

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

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

Related errors

• could not resolve spillover path (empty/invalid id or missin
• context_window must be greater than 0
• custom provider '{provider_id}' must set [providers.{provide
• unknown field '{field_key}' for built-in provider '{provider
• unknown field '{field_key}' for custom provider '{provider_i

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/e73f089e6fa04712. Report an issue: GitHub.