Practical use and limits
Use it for: Keep a short diagnostic transcript: target host, account, offered identity, effective AuthorizedKeysFile, relevant permissions, and the server log line that confirms the fix.
Limits: Commands and permission requirements vary by operating system and sshd configuration. Test one change at a time and preserve a recovery path.
Start by classifying the failure
A timeout or connection refused is not a public-key problem. A host-key warning is not an authorized_keys problem. A message such as Permission denied (publickey) means the server was reached and rejected the available authentication methods or credentials. Keeping these layers separate prevents random permission changes and repeated key generation.
Confirm the client is offering the intended key
Use an explicit IdentityFile for the first test and enable verbose logging with ssh -v or ssh -vv. Check the log for identity files that are loaded and offered. SSH agents, multiple config blocks, aliases, and a default key can cause a different identity to be tried than the one you expected. Once the correct key works, simplify the config and avoid unnecessary identities.
Compare derived public keys
On a trusted machine, derive the public key from the private key and compare the complete OpenSSH public-key line with the server's authorized_keys entry. The algorithm prefix matters: ssh-ed25519 does not match an ECDSA or RSA key. Comments can differ, but the key material and algorithm must match. Do not compare only the filename or a shortened visual fragment.
Inspect the server-side path
For the target account, confirm the expected home directory, .ssh directory, and authorized_keys path. A key placed under /root will not authorize a login as another user. Check that the file contains one complete line per key, with no accidental wrapping or smart quotes. If sshd uses an alternate AuthorizedKeysFile or an included configuration, inspect the effective setting rather than assuming the default.
Fix permissions without making the server weaker
Private keys should be readable only by their owner. On the server, the .ssh directory and authorized_keys file should not be writable by unrelated users, and the account's home path must satisfy the server's strict-mode checks. Use the distribution's documented ownership and mode requirements. Do not solve a permission problem by making the entire home directory or authorized_keys world-writable.
Check account policy and server logs
If the key matches and the path is correct, inspect the effective sshd configuration, the target shell, account lock or expiry state, AllowUsers and AllowGroups rules, authentication method policy, and server authentication logs. A rejected key can be caused by policy even when the cryptographic material is correct. Make one change at a time, test, and retain the log line that proves the result.
Bottom line
Most public-key failures become straightforward when you ask five questions in order: Did I reach the intended server? Did it present the expected host key? Did the client offer the intended private key? Did the server read the matching public key? Did policy allow that account to authenticate? This checklist is safer and faster than regenerating credentials until something happens to work.
Frequently asked questions
Why does SSH say publickey when my file exists?
A file path proves only that a file exists. The client may reject its format, offer another key, or the server may not contain the matching public key for the requested account.
Do comments at the end of authorized_keys matter?
Normally comments are labels and do not affect the key. The algorithm and key material must still be intact on one line.
Should I generate a new key immediately?
Not usually. First identify which key is being offered and compare its derived public key with the server record. Generate a replacement when the old key is lost, exposed, or intentionally being rotated.