rust-lang/cargo · error

utf-8 home

Error message

utf-8 home

What it means

Panic while building the 'add this SSH host key' error message in user_known_host_location_to_add (src/sources/git/known_hosts.rs:572). cargo computes the user's known_hosts path from home::home_dir() (~/.ssh/known_hosts) and calls path.to_str().expect("utf-8 home"). Path::to_str() returns None when the path contains bytes that are not valid UTF-8, so the panic fires only when the user's home directory itself is non-UTF-8 AND cargo simultaneously needs to print a 'host key not known' message for a git SSH dependency.

Source

Thrown at src/sources/git/known_hosts.rs:572

    // - Unix: $HOME, or getpwuid_r()
    //
    // Since there is a mismatch here, the location returned here might be
    // different than what the user's `ssh` CLI command uses. We may want to
    // consider trying to align it better.
    home::home_dir().map(|mut home| {
        home.push(".ssh");
        home.push("known_hosts");
        home
    })
}

/// The location to display in an error message instructing the user where to
/// add the new key.
fn user_known_host_location_to_add(diagnostic_home_config: &str) -> String {
    // Note that we don't bother with the legacy known_hosts2 files.
    let user = user_known_host_location();
    let openssh_loc = match &user {
        Some(path) => path.to_str().expect("utf-8 home"),
        None => "~/.ssh/known_hosts",
    };
    format!(
        "the `net.ssh.known-hosts` array in your Cargo configuration \
        (such as {diagnostic_home_config}) \
        or in your OpenSSH known_hosts file at {openssh_loc}"
    )
}

const HASH_HOSTNAME_PREFIX: &str = "|1|";

#[derive(Clone)]
enum KnownHostLineType {
    Key,
    CertAuthority,
    Revoked,
}

View on GitHub (pinned to 0e07a15537)

Solutions

1. Make HOME (or USERPROFILE on Windows) a valid UTF-8 path: rename the offending directory / username or export HOME to an ASCII path, then retry the git+ssh fetch.
2. Avoid the known_hosts file path entirely by pre-declaring the host key in cargo config: add an entry under [net.ssh] known-hosts in ~/.cargo/config.toml so cargo never has to render the 'add to ~/.ssh/known_hosts' message.
3. Pre-populate ~/.ssh/known_hosts with the host (e.g. `ssh-keyscan example.com >> ~/.ssh/known_hosts`) so cargo finds the key and never reaches the message-building code.
4. Run cargo from a shell/locale where the home directory decodes as UTF-8 (LC_ALL=C.UTF-8 or en_US.UTF-8).

Example fix

# before: HOME contains non-UTF-8 bytes; any unknown ssh host panics
#   thread 'main' panicked at src/sources/git/known_hosts.rs:572: utf-8 home

# after: point HOME at a UTF-8 path, or pre-trust the key in cargo config
export HOME=/home/runner   # an ASCII / valid-UTF-8 directory
# ~/.cargo/config.toml:
#   [net.ssh]
#   known-hosts = ["github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UO3qL..."]

use std::path::Path;

// Run before any git+ssh dependency fetch that may render a known-hosts error.
fn home_is_utf8() -> bool {
    match home::home_dir() {
        Some(p) => Path::new(&p).to_str().is_some(),
        None    => true, // None branch uses "~/.ssh/known_hosts" literal, never panics
    }
}

// Safer still: bypass the file path by declaring trusted keys in cargo config.

fn utf8_home_path(p: &std::path::Path) -> Option<&str> {
    p.to_str() // None iff non-UTF-8; use this to decide whether the SSH message path is safe to build
}

// The panic is in error-message formatting, not the real check.
// Avoid it structurally: pre-trust the host so cargo never builds the 'add to ~/.ssh/known_hosts' message.
// ~/.cargo/config.toml -> [net.ssh] known-hosts = ["host key-type key"]
// or: ssh-keyscan host >> ~/.ssh/known_hosts

When it happens

Trigger: A git+ssh dependency whose host key is not in ~/.ssh/known_hosts or in cargo's net.ssh.known-hosts config, combined with a HOME / USERPROFILE whose filesystem path is non-UTF-8 (legacy locale-specific username bytes, a non-UTF-8 mount, or a mangled env var). The panic happens during error-message rendering, not during the actual key check.

Common situations: Linux/macOS accounts whose home directory was created under a non-UTF-8 locale; containers with a HOME pointing at a path containing invalid UTF-8 bytes; CI images where HOME is overridden to a raw byte string; rare Windows USERPROFILE values with encoding issues.

Related errors

• must be utf-8 in toml
• path at `{}` was not valid utf-8
• Character at line {} is invalid. Cargo only supports UTF-8.
• path does not have a unicode filename which may not unpack o
• error: failed to validate host key: {:#}

AI-assisted analysis of rust-lang/cargo@0e07a15537 (2026-08-06). Data as JSON: /data/errors/05222606658dc0fe.json. Report an issue: GitHub.