Hmbown/CodeWhale · error · io::Error

could not resolve session artifact path (missing home…

Error message

could not resolve session artifact path (missing home directory)

What it means

Public entry `write_session_artifact` builds an absolute artifact path under the user's home directory. When the home directory cannot be resolved, `session_artifact_absolute_path` returns None and this InvalidInput io::Error is thrown instead of writing the file.

Solutions

1. Set HOME to an existing writable directory for the process (e.g. `export HOME=/home/user` or systemd `Environment=HOME=...`).
2. Run under a user account that has a valid home directory in /etc/passwd.
3. In containers, create the home directory and pass it explicitly.
4. Prefer APIs that accept an explicit base directory if operating in a headless service context.

Example fix

// before (systemd unit)
[Service]
ExecStart=/usr/local/bin/codewhale

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

fn artifact_env_ready() -> bool {
    std::env::var_os("HOME").map(|h| !h.is_empty()).unwrap_or(false)
}

fn home_dir() -> Option<std::path::PathBuf> {
    std::env::var_os("HOME").filter(|h| !h.is_empty()).map(std::path::PathBuf::from)
}

match write_session_artifact(session, id, content) {
    Err(e) if e.to_string().contains("missing home directory") => {
        // configure HOME or switch to an explicit-root API
    }
    other => other?,
}

When it happens

Trigger: Calling `write_session_artifact` in an environment where the home directory is unavailable: HOME unset, no passwd entry for the user, or running in a stripped container/service context.

Common situations: Running under systemd with no HOME, inside minimal Docker images, cron jobs without a full environment, or CI sandboxes without user home directories.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• invalid session artifact path
• CODEWHALE_HOME / user home is unavailable
• could not resolve home directory for FileKeyringStore
• <state dir resolution error>
• tempdir

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

Appendix: source

Thrown at crates/tui/src/artifacts.rs:142

    {
        return None;
    }
    Some(
        artifact_sessions_root()?
            .join(session_id)
            .join(relative_path),
    )
}

pub fn write_session_artifact(
    session_id: &str,
    artifact_id: &str,
    content: &str,
) -> io::Result<(PathBuf, PathBuf)> {
    let relative_path = session_artifact_relative_path(artifact_id);
    let absolute_path =
        session_artifact_absolute_path(session_id, &relative_path).ok_or_else(|| {
            io::Error::new(
                io::ErrorKind::InvalidInput,
                "could not resolve session artifact path (missing home directory)",
            )
        })?;
    if let Some(parent) = absolute_path.parent() {
        std::fs::create_dir_all(parent)?;
    }
    crate::utils::write_atomic(&absolute_path, content.as_bytes())?;
    Ok((absolute_path, relative_path))
}

/// Publish immutable session-owned bytes without replacing an earlier handle.
/// A duplicate replay with identical bytes is idempotent; a different payload
/// for the same relative path fails closed.
pub fn write_session_relative_immutable(
    session_id: &str,
    relative_path: &Path,
    content: &[u8],

View on GitHub (pinned to 73e0f67d83)