Troubleshooting the "Permission denied (publickey)" error can be challenging, especially when SSH keys fail to authenticate. This guide will help you systematically identify and fix the root cause of the problem.
Understanding the Issue
When connecting to a remote server via SSH, you may encounter the error:
Permission denied (publickey).This occurs when the server cannot match your private key with a corresponding public key. SSH relies on a pair of keys for secure communication:
- Private key: Stored locally on your device.
- Public key: Stored in the server's
~/.ssh/authorized_keys.
For authentication to succeed:
- Your private key must match the server's public key.
- Both keys must be correctly configured on their respective systems.
Prepare for Troubleshooting
prerequisites
- Access to the SSH client machine's
.sshdirectory. - Control over the remote server, either remotely or through a hosting provider.
- Familiarity with terminal commands.
Validate Key Files Locally
Ensure the SSH client can locate and use the correct key pair.
steps
Open a terminal and navigate to your SSH directory:
bashcd ~/.ssh lsConfirm the presence of key files like
id_rsa(private key) andid_rsa.pub(public key).Verify the key pair matches:
bashssh-keygen -y -f id_rsa- Compare the output against
id_rsa.pubusing:bashcat id_rsa.pub - Ensure the keys are identical.
- Compare the output against
Check SSH Configuration
Review the local SSH configuration file to ensure it references the correct key identity.
steps
- Open the configuration file:bash
nano ~/.ssh/config - Verify or add the
IdentityFiledirective:ReplaceHost * IdentityFile ~/.ssh/id_rsaid_rsawith your private key name if customized. - Save changes and exit the editor (
Ctrl + X, thenY, thenEnter).
Diagnose Using SSH Verbose Mode
Verbose mode provides detailed output on why the SSH connection fails.
Run SSH in verbose mode
ssh -v username@server_ip
# Look for lines like:
# debug1: Offering public key: /home/user/.ssh/id_rsa
# debug1: Server accepts key: no- Focus on lines indicating whether the suggested private key was used or rejected.
Inspect and Update Server-Side Setup
If the local keys are correct, verify the server configuration.
steps
- Access the server via an alternative method (e.g., another authorized user, web console).
- Navigate to the server's SSH directory:bash
cd ~/.ssh nano authorized_keys - If the file is empty or missing your public key, add your local
id_rsa.pubcontents. - Save changes and ensure correct file permissions:bash
chmod 600 ~/.ssh/authorized_keys chmod 700 ~/.ssh
Common Provider Solutions
Verification and Retesting
Once adjustments are made, retry the SSH connection.
Recap and FAQ
FAQ
Why does "Permission denied (publickey)" appear during SSH?
This error means the server cannot verify your private key against its authorized public keys. The problem may stem from missing keys, incorrect file permissions, or misconfigured SSH settings.
How do I check which key my SSH client offers?
Run your SSH command in verbose mode with ssh -v. Look for lines about Offering public key to verify which key the client attempts to use.
What should file permissions be for SSH keys?
On the client:
~/.sshdirectory:700- Private key:
600
On the server:
~/.sshdirectory:700authorized_keysfile:600
Can I recover access without SSH keys?
If password-based login is allowed, use your username and password. Alternatively, use your hosting provider's emergency access tools like a web console or reset the SSH keys through their dashboard.
Official reference: OpenSSH manual pages.