FuelLabs/sway · critical

unable to find the user home directory

Error message

unable to find the user home directory

What it means

forc-util's user_forc_directory() computes $HOME/.forc, the base for git checkouts, caches and several defaults across the forc toolchain. dirs::home_dir() returns None when HOME is unset (Unix) or the user profile cannot be determined (Windows), and this expect panics, taking down whatever forc command reached the call.

Source

Thrown at forc-util/src/lib.rs:221

    if restricted::is_non_ascii_name(name) {
        bail!("the name `{name}` contains non-ASCII characters which are unsupported");
    }
    Ok(())
}

/// Simple function to convert kebab-case to snake_case.
pub fn kebab_to_snake_case(s: &str) -> String {
    s.replace('-', "_")
}

pub fn default_output_directory(manifest_dir: &Path) -> PathBuf {
    manifest_dir.join(DEFAULT_OUTPUT_DIRECTORY)
}

/// Returns the user's `.forc` directory, `$HOME/.forc` by default.
pub fn user_forc_directory() -> PathBuf {
    dirs::home_dir()
        .expect("unable to find the user home directory")
        .join(constants::USER_FORC_DIRECTORY)
}

/// The location at which `forc` will checkout git repositories.
pub fn git_checkouts_directory() -> PathBuf {
    user_forc_directory().join("git").join("checkouts")
}

/// Given a path to a directory we wish to lock, produce a path for an associated lock file.
///
/// Note that the lock file itself is simply a placeholder for co-ordinating access. As a result,
/// we want to create the lock file if it doesn't exist, but we can never reliably remove it
/// without risking invalidation of an existing lock. As a result, we use a dedicated, hidden
/// directory with a lock file named after the checkout path.
///
/// Note: This has nothing to do with `Forc.lock` files, rather this is about fd locks for
/// coordinating access to particular paths (e.g. git checkout directories).
fn fd_lock_path<X: AsRef<Path>>(path: X) -> PathBuf {

View on GitHub (pinned to 47e5e902fa)

Solutions

1. Set HOME explicitly for the build context: `docker run -e HOME=/root ...` or `export HOME=$PWD/.home` in CI scripts.
2. For services, add `Environment="HOME=/path"` to the unit file or ensure the run user has a home directory in /etc/passwd.
3. Create and persist the directory you point HOME at so .forc caches survive between runs.

Example fix

# before
$ docker run --rm myimg forc build
thread 'main' panicked: unable to find the user home directory
# after
$ docker run --rm -e HOME=/root -v forc-cache:/root/.forc myimg forc build

# container/CI entrypoint: guarantee HOME before any forc command
if [ -z "${HOME:-}" ]; then
  export HOME="$PWD/.home"
  mkdir -p "$HOME"
fi
forc build

When it happens

Trigger: Running any forc command in a container, service, or cron context where HOME is unset (docker run without -e HOME, systemd unit without Environment, `sudo -E` stripping); running as a user with no passwd home entry; CI runners that clear the environment.

Common situations: Dockerfiles that set USER without providing HOME; Kubernetes/CI pods with minimal env; scheduled tasks; building inside sandboxed agents that drop env vars.

Related errors

• Failed to execute ps command
• Failed to execute tasklist command
• Could not get homedir
• Failed to execute ps command
• Could not get plugin description.

AI-assisted analysis of FuelLabs/sway@47e5e902fa (2026-08-16). Data as JSON: /api/errors/f8e35e0f61735d6f. Report an issue: GitHub.