SSH Permission Denied (Publickey) Debugging Guide

When you encounter the error message "SSH permission denied (publickey)", it signifies that your SSH client failed to authenticate with the remote server using the public key method. This common issue often stems from incorrect file permissions on either your local private key or the server's authorized_keys file, using the wrong private key, or specific misconfigurations within the server's sshd_config file. To effectively debug this, you should first confirm correct private key permissions (typically 600), then verify the public key's presence and permissions (600) in the server's ~/.ssh/authorized_keys, and finally, consult the server's authentication logs, such as /var/log/auth.log, for precise failure details.

Understanding SSH Public Key Authentication

Public key authentication forms the cornerstone of secure SSH connections, offering a more robust alternative to password-based logins. This method relies on a cryptographic key pair: a public key stored on the server and a corresponding private key held securely on your client machine. When you initiate an SSH connection, the server challenges your client, which then proves its identity by demonstrating possession of the private key without ever transmitting the key itself. The entire process is governed by protocols like those outlined in IETF RFC 4252, The Secure Shell (SSH) Authentication Protocol, ensuring a highly secure handshake.

Your public key, usually named id_rsa.pub or id_ed25519.pub, resides on the remote server within a file typically located at ~/.ssh/authorized_keys in the user's home directory. This file can contain multiple public keys, each granting access to a different client or user. The private key, often id_rsa or id_ed25519, must be kept strictly confidential on your local machine. Its permissions are paramount for security and functionality; any deviation from the expected 600 (read/write only for the owner) will cause the SSH client to refuse to use it.

When you attempt to connect, your client presents its public key to the server. The server then encrypts a random string with that public key and sends it back. Your client decrypts the string using its private key and sends it back to the server. If the decrypted string matches the original, the server confirms your identity and grants access. This intricate dance ensures that only authorized users with the correct private key can establish a connection, making proper configuration essential for successful logins.

Initial Checks: Quick Fixes for "Permission Denied"

Before diving into deeper diagnostics, a few straightforward checks can often resolve "permission denied" errors. These initial steps help confirm that the most basic parameters for your SSH connection are correct, saving time on more complex troubleshooting. Overlooking simple typos or incorrect key selections is a common pitfall that many users encounter when managing server access.

Confirming Key Usage and Connection Details

Always ensure you are specifying the correct private key for the connection, especially if you manage multiple key pairs. The -i flag followed by the path to your private key explicitly tells the ssh client which identity file to use. For example, if your private key is ~/.ssh/my_server_key, your command would be ssh -i ~/.ssh/my_server_key user@host. Verify the username and hostname (or IP address) are accurate, as a mismatch will prevent authentication. Default SSH port is 22, but some servers use a non-standard port; if so, use -p PORT_NUMBER.

# Correct usage of the -i flag for a specific key
ssh -i ~/.ssh/my_server_key your_username@your_server_ip

# Example with a non-standard port (e.g., 2222)
ssh -i ~/.ssh/my_server_key -p 2222 your_username@your_server_ip

Basic Connectivity Test

A quick way to check if the server is even reachable and listening on the SSH port is to use the ssh command with the verbose flag, but without attempting authentication initially. This helps differentiate network issues from authentication problems. Run ssh -v your_username@your_server_ip (or include -p if needed). Look for lines indicating successful connection (debug1: Connection established) or network errors. If you see "Connection refused" or a timeout, the problem might be a firewall, an incorrect port, or sshd not running on the server. This diagnostic step is crucial because a network-level blockage will prevent any authentication attempt from even reaching the SSH daemon.

Client-Side Debugging: Your Local Machine

Issues on your local machine are frequently the cause of "permission denied (publickey)" errors. The SSH client is very particular about file permissions and key management. Improperly secured private keys or incorrect configuration in your local SSH setup will halt the authentication process before it even reaches the server's validation stage, presenting an immediate barrier to connection.

Private Key Permissions (Critical)

The most common client-side cause is incorrect permissions on your private key file. Your SSH client will refuse to use a private key if its permissions are too broad, as this indicates a potential security risk where other users on your system could read or modify it. The private key file (e.g., ~/.ssh/id_rsa) must only be readable and writable by your user, with no access for group or others. The standard, secure permission is 600.

To fix this, open your terminal and run:

chmod 600 ~/.ssh/id_rsa
# Or for other key types like id_ed25519
chmod 600 ~/.ssh/id_ed25519

Additionally, the ~/.ssh directory itself should have 700 permissions (read, write, execute for owner only). While not always strictly enforced for the directory by all SSH clients, it's a critical best practice for maintaining the overall security of your SSH configuration files.

chmod 700 ~/.ssh

Using the SSH Agent

The ssh-agent significantly improves usability by keeping your private keys decrypted in memory, eliminating the need to type your passphrase repeatedly during a session. However, the agent typically runs only for the duration of your terminal session. For persistent agent functionality across reboots or new terminal windows, you can integrate eval "$(ssh-agent -s)" and ssh-add into your shell's startup script, such as ~/.bashrc or ~/.zshrc. Tools like keychain can also manage this persistence more elegantly, especially on systems where you frequently interact with multiple SSH keys. If your key requires a passphrase and isn't added to the agent, the SSH client won't be able to use it, leading to a "permission denied" error.

To start the ssh-agent (if not already running) and add your key:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa
# You will be prompted for your passphrase if your key has one.

You can list keys currently loaded in the agent with ssh-add -l. If your key is missing, add it, ensuring it's available for authentication attempts.

SSH Client Configuration File (~/.ssh/config)

Your local SSH configuration file, ~/.ssh/config, allows you to define aliases and specific settings for different hosts. A misconfiguration here, such as an incorrect IdentityFile path, a conflicting PubkeyAuthentication directive (though rare on the client side), or a typo in the hostname, can lead to denial. This file should also have 600 permissions to prevent unauthorized modification.

Example ~/.ssh/config entry:

Host myremotehost
    HostName your_server_ip_or_hostname
    User your_username
    IdentityFile ~/.ssh/my_server_key
    Port 2222

Ensure that the IdentityFile path is correct and points precisely to your private key. If you are using a managed VPS provider like Valebyte, their documentation might suggest specific ~/.ssh/config settings, which you should cross-reference carefully.

Server-Side Debugging: The Remote Host

Once you've ruled out client-side issues, the problem likely lies on the remote server. Server-side misconfigurations, particularly with file permissions or the sshd_config file, are frequent culprits for "permission denied (publickey)" errors. Accessing the server via an alternative method (like a web-based console, another SSH key that does work, or password authentication if still enabled) is often necessary to perform these checks.

authorized_keys File Permissions

Just like your private key, the ~/.ssh/authorized_keys file on the server must have strict permissions. It should be readable and writable only by the owner (the user you are trying to log in as). The required permission is 600. If the file is more permissive, sshd will ignore it for security reasons.

To correct permissions on the server:

# Log in to the server via console or another method
# Navigate to the user's home directory
cd ~
# Ensure .ssh directory exists and has correct permissions
mkdir -p ~/.ssh
chmod 700 ~/.ssh
# Correct authorized_keys permissions
chmod 600 ~/.ssh/authorized_keys

The parent directory (~) for the user home directory should typically have 755 permissions, meaning it's readable and executable by others but writable only by the owner. This is standard on most Linux distributions like Ubuntu 24.04, but it's worth a quick check: chmod 755 ~.

Examining sshd_config

The main SSH daemon configuration file, typically located at /etc/ssh/sshd_config, dictates how the server accepts SSH connections. Incorrect settings here can override or prevent public key authentication. You'll need root privileges to inspect and modify this file.

Key directives to check in /etc/ssh/sshd_config:

• PubkeyAuthentication yes: This must be set to yes to enable public key authentication.
• AuthorizedKeysFile .ssh/authorized_keys: This specifies the path to the file containing public keys. The default is usually correct, but confirm it hasn't been changed to a non-existent path.
• PermitRootLogin prohibit-password or no: If you're trying to log in as root, ensure this setting allows public key authentication. prohibit-password allows key-based login for root, while no disables it entirely.
• StrictModes yes: This (default) ensures SSH checks file permissions on ~/.ssh and authorized_keys. If it's no, it might bypass checks, but it's a security risk. Keep it yes.

After any changes to sshd_config, you must restart the SSH service for them to take effect. For systemd-based systems (common on modern Linux distributions as of 2026-04):

sudo systemctl restart sshd
# Or on some older systems
sudo service sshd restart

Always test connections after restarting sshd to ensure you haven't locked yourself out. For a comprehensive initial server setup, refer to resources like the Ubuntu 24.04 VPS Hardening Checklist.

Common Permission Issues at a Glance

Incorrect file and directory permissions are by far the most frequent culprits behind "SSH permission denied (publickey)" errors. The SSH daemon (sshd) enforces strict security measures, refusing to use any key or directory that isn't properly secured. Understanding these specific permission requirements is crucial for effective troubleshooting. The following table summarizes the critical files and directories, their expected permissions, and the common commands to correct them as of 2026-04.

Maintaining these precise permissions is not merely a recommendation; it is a fundamental security requirement enforced by the SSH protocol. Any deviation often leads directly to the "permission denied" error, as the system considers improperly secured files a vulnerability. Always ensure these permission checks are among your first steps in debugging.

Advanced Troubleshooting: Verbose Output and Log Analysis

When the basic checks don't yield a solution, delving into the verbose output of the SSH client and the server's authentication logs becomes essential. These detailed records provide specific clues about why the authentication failed, pointing directly to the root cause, which can be elusive without granular information.

Interpreting ssh -vvv Output

The ssh client's verbose output (using -vvv for maximum detail) is invaluable for diagnosing connection issues. It prints every step of the negotiation process, from key exchange to authentication attempts, allowing you to trace the exact point of failure.

ssh -vvv your_username@your_server_ip

Look for lines containing "debug3: send_pubkey_test" or "debug1: Offering public key". If you don't see your key offered, it's a client-side problem (permissions, agent, config). If the key is offered but then rejected, the issue is likely server-side. Specific messages like "debug1: Authentications that can continue: publickey,gssapi-keyex,gssapi-with-mic" followed by "debug1: Authentications that can continue: publickey" often indicate the server is expecting a public key. A crucial line to watch for is "debug1: Server accepts key: ...", if this appears, authentication should succeed. If it fails, look for "debug1: Authentications that can continue: password" or similar, indicating publickey failed.

Correlating Client and Server Logs

The server's authentication logs provide the definitive reason for a failed public key authentication attempt. On most Linux distributions, these logs are found in /var/log/auth.log (Debian/Ubuntu) or /var/log/secure (CentOS/Red Hat). You'll need sudo privileges to read them.

To view recent authentication failures:

# On Debian/Ubuntu
sudo grep "sshd" /var/log/auth.log | tail -n 50

# On CentOS/Red Hat
sudo grep "sshd" /var/log/secure | tail -n 50

Look for entries with Authentication refused: bad ownership or modes, Authentication refused: bad ownership or modes for directory /home/user/.ssh, or User user from client.ip not allowed because of 'no' rule. The timestamps are critical for correlating server logs with your client-side connection attempts. If the server logs indicate issues with authorized_keys permissions, revisit the server-side checks.

Always cross-reference timestamps between your client's ssh -vvv output and the server's auth.log (or secure) to accurately pinpoint the exact moment of failure and its corresponding reason. This correlation is key to effective debugging.

SELinux or AppArmor Interference

In some hardened environments, Mandatory Access Control (MAC) systems like SELinux (Security-Enhanced Linux) or AppArmor can prevent sshd from accessing the authorized_keys file, even if standard file permissions appear correct. While less common, this can be a confounding factor, especially in enterprise deployments or specific Linux distributions.

To check SELinux status:

sestatus

If SELinux is enforcing, you might need to restore the default security contexts for your SSH directory:

sudo restorecon -Rv ~/.ssh

For AppArmor, you can check its status with sudo apparmor_status. If you suspect AppArmor is blocking sshd, temporarily disabling its profile for sshd (not recommended for production) or carefully reviewing its logs (/var/log/kern.log or dmesg) for "apparmor=DENIED" messages related to sshd might be necessary.

Generating New SSH Keys and Best Practices

Sometimes, the simplest solution is to generate a fresh pair of SSH keys and ensure they are correctly set up from scratch. This eliminates any potential corruption or unknown issues with existing keys. Adhering to best practices for key generation and management enhances your server's security posture and streamlines future access.

Step-by-Step: Generating a New SSH Key Pair

Generating a new key pair is a straightforward process using ssh-keygen. It's recommended to use a strong algorithm like Ed25519 (as of 2026-04) due to its efficiency and security over older RSA keys, though RSA is still widely supported.

1. Generate the key pair: Open your local terminal and run:

   ssh-keygen -t ed25519 -C "[email protected]_server_name"

   The -C flag adds a comment to the public key, which is useful for identification, especially when managing multiple keys for different servers or services.
2. Choose a file location: Press Enter to accept the default location (~/.ssh/id_ed25519) or specify a new path. Using a unique name (e.g., ~/.ssh/nelsa_server_id_ed25519) is beneficial if you manage multiple keys, preventing overwrites.
3. Set a strong passphrase: It's highly recommended to protect your private key with a strong, unique passphrase. This adds an extra layer of security, requiring the passphrase to decrypt the key even if the file is compromised. Forgetting your passphrase will render your key unusable.
4. Confirm key files: After generation, you'll have two files: id_ed25519 (private key) and id_ed25519.pub (public key) in your ~/.ssh directory. Verify their permissions are 600 for the private key and 644 for the public key.

For more details on ssh-keygen options, consult the official ssh-keygen man page, which offers extensive information on key types and usage.

Deploying the New Public Key to the Server

The easiest and most secure way to deploy your new public key to a server is using ssh-copy-id. This utility handles placing the public key in the correct location (~/.ssh/authorized_keys) with the appropriate permissions, automating a crucial step.

ssh-copy-id -i ~/.ssh/nelsa_server_id_ed25519.pub your_username@your_server_ip

If ssh-copy-id isn't available or you need to do it manually:

1. Copy the public key content:

   cat ~/.ssh/nelsa_server_id_ed25519.pub

   Copy the entire output, including the ssh-ed25519 prefix and the comment at the end.
2. Log into the server using an alternative method (e.g., password or another working key).
3. Append the public key to authorized_keys:

   mkdir -p ~/.ssh
   chmod 700 ~/.ssh
   echo "PASTE_YOUR_PUBLIC_KEY_HERE" >> ~/.ssh/authorized_keys
   chmod 600 ~/.ssh/authorized_keys

   Replace "PASTE_YOUR_PUBLIC_KEY_HERE" with the content you copied. Ensure there are no extra line breaks or characters.

After deployment, attempt to connect to the server with your new key: ssh -i ~/.ssh/nelsa_server_id_ed25519 your_username@your_server_ip. This process ensures a clean slate and adherence to best practices for key-based authentication. If you're managing multiple applications on a VPS, such as hosting n8n, proper SSH access is crucial for deployment and maintenance, as detailed in guides like How to Host n8n on a VPS.