PuTTY Pageant SSH key authentication failures: diagnostic guide

Problem: PuTTY rejects Pageant keys with publickey errors

You start PuTTY, connect to a Linux server, and see Permission denied (publickey) or Authentication failed even though Pageant is running and you loaded the correct .ppk private key. Pageant is PuTTY’s SSH authentication agent: it holds decrypted private keys in memory so PuTTY can offer them during connection without prompting for a passphrase each time.

Useful takeaway: a running Pageant icon is not enough. The key must be loaded into the correct Pageant instance, PuTTY must be configured to use Pageant, and the server must have the matching public key in the right account’s ~/.ssh/authorized_keys file.

Recognizable conditions and likely causes

Condition	Most likely cause
Pageant tray icon missing	Pageant is not running, or a different user’s instance is running
Pageant key list is empty	No private key loaded, or the session ended after a crash
Key loaded but PuTTY reports No key found	PuTTY is not attempting agent authentication, or Pageant is locked
Server refuses the key	Wrong public key on server, wrong file permissions, or sshd_config disables pubkey auth

Ordered checks

1. Confirm Pageant is running and unlocked

   Look for the Pageant icon in the Windows system tray. Double-click it to open the key list. If the window asks for a passphrase, Pageant is locked; unlock it before PuTTY can use the key.

2. Verify the correct key is loaded

   In the Pageant window, compare the key comment and fingerprint against the key you expect for this host. A key comment such as rsa-key-20240101 does not prove it matches the server’s authorized_keys entry.

3. Check PuTTY session settings

   Open PuTTY, load the session, go to Connection > SSH > Auth. Ensure Attempt authentication using Pageant is checked. If you also specify a private key file under Private key file for authentication, PuTTY may use that file instead of Pageant; clear it if you want Pageant to supply the key.

4. Capture a verbose PuTTY log

   In PuTTY, go to Session > Logging, select Show all log messages, choose a log file path, and connect. Look for lines such as Offering public key followed by Server refused our key or No key found. This distinguishes client-side key selection from server-side rejection.

5. Inspect server authentication logs

   Run on the SSH server. Required permissions: root or sudo. Placeholder: /var/log/auth.log.

   sudo grep 'sshd' /var/log/auth.log | tail -n 50

   Expected check: lines for your connection attempt mentioning publickey and either Accepted or Refused. If the log shows a different key fingerprint than your Pageant key, the server is not configured for the key you loaded.

   Risk: log files may be rotated or located at /var/log/secure on some distributions. Do not edit logs while diagnosing.

6. Compare key fingerprints

   On the server, list the fingerprint of the authorized key:

   ssh-keygen -l -f ~/.ssh/authorized_keys

   On Windows, open the key in PuTTYgen and read the fingerprint, or check Pageant’s key list if it displays one. They must match. Fingerprint formats differ between MD5 and SHA256 depending on OpenSSH version, so compare the same type.

Fixes tied to findings

• Pageant not running: start pageant.exe, add the .ppk file, then retry the PuTTY connection.
• Wrong key loaded: remove keys from Pageant, load the correct key, and reconnect.
• PuTTY not using Pageant: in the session, enable Attempt authentication using Pageant and clear any static Private key file for authentication path.
• Server missing public key: append the matching public key to the target account’s ~/.ssh/authorized_keys on the server. Ensure the file is owned by that user and mode 600, and the ~/.ssh directory is mode 700.
• sshd rejects pubkey auth: check /etc/ssh/sshd_config for PubkeyAuthentication yes. sshd_config is the OpenSSH server configuration file. After editing, reload sshd, then test again.

Rollback

Adding a key to Pageant changes only that session’s memory. To undo, exit Pageant from the system tray and restart it without loading the key. Back up authorized_keys and sshd_config before editing server files.

Escalation criteria

Escalate to the server administrator if:

• PuTTY logs show the key was offered and refused, but the server logs contain no matching entry, suggesting a different sshd instance or chrooted logging.
• PubkeyAuthentication is set globally and you cannot change sshd_config.
• The key works from another client but not PuTTY, indicating a possible PuTTY key-format issue; check the release notes for your PuTTY version before proceeding.

Limitations and verification

This guide covers PuTTY with Pageant on Windows connecting to OpenSSH servers. Behavior may differ between PuTTY releases; check Help > About for your version. This draft has not been verified against a live PuTTY installation; confirm each step in a non-production environment first.

Practical check: after applying a fix, open a new PuTTY session to the same host. Success is a shell prompt without a password prompt and an Accepted publickey line in the server log.