{"id":"05222606658dc0fe","repo":"rust-lang/cargo","slug":"utf-8-home","errorCode":null,"errorMessage":"utf-8 home","messagePattern":"utf-8 home","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/sources/git/known_hosts.rs","lineNumber":572,"sourceCode":"    // - Unix: $HOME, or getpwuid_r()\n    //\n    // Since there is a mismatch here, the location returned here might be\n    // different than what the user's `ssh` CLI command uses. We may want to\n    // consider trying to align it better.\n    home::home_dir().map(|mut home| {\n        home.push(\".ssh\");\n        home.push(\"known_hosts\");\n        home\n    })\n}\n\n/// The location to display in an error message instructing the user where to\n/// add the new key.\nfn user_known_host_location_to_add(diagnostic_home_config: &str) -> String {\n    // Note that we don't bother with the legacy known_hosts2 files.\n    let user = user_known_host_location();\n    let openssh_loc = match &user {\n        Some(path) => path.to_str().expect(\"utf-8 home\"),\n        None => \"~/.ssh/known_hosts\",\n    };\n    format!(\n        \"the `net.ssh.known-hosts` array in your Cargo configuration \\\n        (such as {diagnostic_home_config}) \\\n        or in your OpenSSH known_hosts file at {openssh_loc}\"\n    )\n}\n\nconst HASH_HOSTNAME_PREFIX: &str = \"|1|\";\n\n#[derive(Clone)]\nenum KnownHostLineType {\n    Key,\n    CertAuthority,\n    Revoked,\n}\n","sourceCodeStart":554,"sourceCodeEnd":590,"githubUrl":"https://github.com/rust-lang/cargo/blob/0e07a155371a6ce88ae53a2c00df940280c09a67/src/sources/git/known_hosts.rs#L554-L590","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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.","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.","Run cargo from a shell/locale where the home directory decodes as UTF-8 (LC_ALL=C.UTF-8 or en_US.UTF-8)."],"exampleFix":"# before: HOME contains non-UTF-8 bytes; any unknown ssh host panics\n#   thread 'main' panicked at src/sources/git/known_hosts.rs:572: utf-8 home\n\n# after: point HOME at a UTF-8 path, or pre-trust the key in cargo config\nexport HOME=/home/runner   # an ASCII / valid-UTF-8 directory\n# ~/.cargo/config.toml:\n#   [net.ssh]\n#   known-hosts = [\"github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UO3qL...\"]","handlingStrategy":"validation","validationCode":"use std::path::Path;\n\n// Run before any git+ssh dependency fetch that may render a known-hosts error.\nfn home_is_utf8() -> bool {\n    match home::home_dir() {\n        Some(p) => Path::new(&p).to_str().is_some(),\n        None    => true, // None branch uses \"~/.ssh/known_hosts\" literal, never panics\n    }\n}\n\n// Safer still: bypass the file path by declaring trusted keys in cargo config.\n","typeGuard":"fn utf8_home_path(p: &std::path::Path) -> Option<&str> {\n    p.to_str() // None iff non-UTF-8; use this to decide whether the SSH message path is safe to build\n}\n","tryCatchPattern":"// The panic is in error-message formatting, not the real check.\n// Avoid it structurally: pre-trust the host so cargo never builds the 'add to ~/.ssh/known_hosts' message.\n// ~/.cargo/config.toml -> [net.ssh] known-hosts = [\"host key-type key\"]\n// or: ssh-keyscan host >> ~/.ssh/known_hosts","preventionTips":["Keep HOME / USERPROFILE as valid UTF-8 in dev shells and CI images.","Pre-declare git SSH hosts in [net.ssh] known-hosts in cargo config so the file-path code path is never reached for unknown keys.","Pre-populate ~/.ssh/known_hosts with ssh-keyscan for hosts used by git dependencies.","In containers, set HOME to a deterministic ASCII path."],"tags":["ssh","known-hosts","utf-8","filesystem","encoding","locale","rust"],"analyzedSha":"0e07a155371a6ce88ae53a2c00df940280c09a67","analyzedAt":"2026-08-06T01:46:58.334Z","schemaVersion":2}