Handle an SSH host key change safely

Verify the new host key independently before updating the correct known_hosts entry, including hashed names and nonstandard ports.

Guance Editorial Team 2026-10-27 3 min read Updated 2026-10-27

Best practices

Illustration of application modules working together

An SSH host key change requires verification before you update known_hosts. A rebuilt server can legitimately have a new key, but an unexpected key can also mean DNS or routing has sent you to another machine, or that someone is impersonating the server.

Verify the new fingerprint independently

Use a trusted administrative channel, such as the cloud console, to obtain the server's public host key fingerprint:

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

Use the key type presented by the connection. Compare the full fingerprint with the one reported by the client. Knowing that a server was rebuilt is useful context, but it does not establish that the current network peer is that server.

Expected changes include an OS reinstall, deliberate host key rotation, a replacement instance using an old IP, or a DNS record moved to another machine. ssh-keygen -A creates missing default host keys; it does not overwrite existing ones.

If you cannot verify the change, stop the connection and investigate. Fetching a key with ssh-keyscan over the same untrusted path does not independently authenticate it.

Replace only the affected trust entry

After verification, remove the old entry for the address you actually use:

ssh-keygen -R server.example.com
# If you connect by IP instead:
ssh-keygen -R 192.168.1.100
# A nondefault port uses a bracketed host-and-port entry:
ssh-keygen -R '[server.example.com]:2222'

The utility handles hashed entries as well. If the warning names another file, use -f /path/to/known_hosts and inspect that file. The original file is normally retained with an .old suffix.

Reconnect and accept the key only if its fingerprint matches the independently verified value. Do not delete the whole trust file to fix one host.

Windows and other clients

Windows OpenSSH supports the same ssh-keygen -R workflow. Its default user file is %USERPROFILE%\.ssh\known_hosts. If you edit it manually, use the exact file and offending line reported by SSH, make a backup, and remove only the verified obsolete entry.

PuTTY maintains its own host key cache, normally in the Windows registry. Updating an OpenSSH file will not update PuTTY. Verify the fingerprint before accepting the client's replacement-key prompt.

Prevent repeated surprises

Reused DHCP addresses and frequently rebuilt machines benefit from stable naming, managed host-key inventories, or SSH host certificates. These need a deliberate trust-management process.

StrictHostKeyChecking=accept-new accepts previously unknown hosts automatically but still rejects changed keys for known hosts. It does not solve this warning, and first-contact trust still needs consideration in fleet automation. Turning host-key checking off removes the protection the warning provides.

A host mismatch is evidence that the identity differs from your recorded expectation; it does not, by itself, prove a specific attack such as ARP spoofing. Check both legitimate infrastructure changes and the network path.

References: ssh-keygen and SSH host-key checking.