rust-lang/cargo · error · anyhow::Error

error: unknown SSH host key The SSH host key for `{hostname}

Error message

error: unknown SSH host key
The SSH host key for `{hostname}` is not known and cannot be validated.

To resolve this issue, add the host key to {known_hosts_location}

The key to add is:

{hostname} {key_type_name} {remote_host_key}

The {key_type_short_name} key fingerprint is: SHA256:{remote_fingerprint}
This fingerprint should be validated with the server administrator that it is correct.
{other_hosts_message}
See https://doc.rust-lang.org/stable/cargo/appendix/git-authentication.html#ssh-known-hosts for more information.

What it means

First-connection case: the SSH host key presented by `hostname` is not found in any known_hosts source (Cargo's bundled list, `~/.ssh/known_hosts`, or Cargo config `net.ssh.known-hosts`). Cargo refuses to trust an unseen key by default to prevent man-in-the-middle attacks. The message shows the exact key line and fingerprint to verify and add.

Source

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

            let other_hosts_message = if other_hosts.is_empty() {
                String::new()
            } else {
                let mut msg = String::from(
                    "Note: This host key was found, \
                    but is associated with a different host:\n",
                );
                for known_host in other_hosts {
                    write!(
                        msg,
                        "    {loc}: {patterns}\n",
                        loc = known_host.location,
                        patterns = known_host.patterns
                    )
                    .unwrap();
                }
                msg
            };
            anyhow::bail!(
                "error: unknown SSH host key\n\
                The SSH host key for `{hostname}` is not known and cannot be validated.\n\
                \n\
                To resolve this issue, add the host key to {known_hosts_location}\n\
                \n\
                The key to add is:\n\
                \n\
                {hostname} {key_type_name} {remote_host_key}\n\
                \n\
                The {key_type_short_name} key fingerprint is: SHA256:{remote_fingerprint}\n\
                This fingerprint should be validated with the server administrator that it is correct.\n\
                {other_hosts_message}\n\
                See https://doc.rust-lang.org/stable/cargo/appendix/git-authentication.html#ssh-known-hosts \
                for more information.\n\
                "
            )
        }
        Err(KnownHostError::HostKeyHasChanged {

View on GitHub (pinned to 0e07a15537)

Solutions

1. Verify the fingerprint with the server administrator, then add the suggested line to `~/.ssh/known_hosts` (or to `net.ssh.known-hosts` in `.cargo/config.toml`).
2. Connect once via `ssh <host>` (or `ssh -p <port> <host>`) and accept the key, so the system SSH writes it to known_hosts.
3. Set `net.git-fetch-with-cli = true` and use the system `git`/`ssh` which manages known_hosts interactively.
4. For CI, pre-seed `~/.ssh/known_hosts` with the host key (e.g. via `ssh-keyscan`).

Example fix

# before: cargo fetch fails on new SSH host
# after
ssh-keyscan -H example.com >> ~/.ssh/known_hosts
cargo fetch

# Pre-seed known_hosts for git deps before cargo fetch:
HOST="$(echo "$GIT_DEP_URL" | sed -nE 's#.*@([^:/]+).*#\1#p')"
ssh-keyscan -H "$HOST" >> ~/.ssh/known_hosts
# Or configure in .cargo/config.toml:
# [net.ssh.known-hosts]
# example.com = "ssh-ed25519 AAAA..."

When it happens

Trigger: Cloning a private git dependency over SSH from a host never connected to before; connecting to a self-hosted GitLab/Gitea/Forgejo; using a non-standard port (the code retries without the port before bailing). The `HostKeyNotFound` variant fires when `check_ssh_known_hosts` finds no match.

Common situations: New SSH git dependency added to `Cargo.toml`; fresh machine/CI without the host's key in known_hosts; corporate git server not in Cargo's bundled known hosts; non-standard SSH port.

Related errors

• error: failed to validate host key: {:#}
• error: SSH host key has changed for `{hostname}` ***********
• error: Key has been revoked for `{hostname}` ***************
• error: Found a `@cert-authority` marker for `{hostname}` Ca
• utf-8 home

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