Permission denied (publickey)
The "Permission denied (publickey)" error occurs when Git cannot authenticate your SSH key while connecting to a remote repository.
Usually happens because:
- ☑ SSH Key has not been added to your GitHub settings profile
- ☑ SSH agent is not running on your host machine
- ☑ Your private key file (~/.ssh/id_ed25519) lacks executable/read permissions
🔍 Quick Checklist:
What is Permission denied (publickey)?
Git attempted to connect to the remote repository using SSH authentication. The SSH server rejected your identity because it could not verify your public key. Git stops the connection before any repository data is transferred. This usually happens because your SSH key is missing, not added to your Git account, or your SSH agent is not running.
Common Causes
- No SSH key exists: An SSH keypair has not been generated on your local machine.
- SSH key not added to Git account: The public key is missing from your profile on GitHub, GitLab, or Bitbucket.
- Wrong remote URL: The repository clone URL is using SSH format, but you wanted to use HTTPS, or it points to the wrong account/repo.
- SSH agent is not running: The background service responsible for holding your private key is offline.
- Incorrect file permissions: The private key file (~/.ssh/id_ed25519) has loose permissions, causing OpenSSH to reject it.
- Wrong SSH configuration: The SSH config file (~/.ssh/config) references the wrong host alias or key path.
- Repository access denied: You do not have read or write permissions to the repository namespace.
- Wrong Git account: Your active SSH key belongs to a different account than the one hosting the private repository.
| Cause | Frequency |
|---|---|
| SSH Key not added to Git account | ⭐⭐⭐⭐⭐ |
| SSH agent not running or key not added | ⭐⭐⭐⭐ |
| Missing local SSH key pair | ⭐⭐⭐ |
Common Mistakes
- Uploading the private key (~/.ssh/id_ed25519) instead of the public key (~/.ssh/id_ed25519.pub) to Git hosting providers.
- Using SSH format remote URLs in public environments where only HTTPS outbound traffic is allowed through firewalls.
How to Fix
Git Operations & Verification
Running push commands when keys are not loaded or registered results in authentication denial.
$ git push origin main
Permission denied (publickey)
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.Platform Specific Fixes
Configure macOS to store key passphrases inside the system Keychain across restarts.
# Edit ~/.ssh/config file
Host github.com
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_ed25519Best Practices
- Always generate separate SSH keypairs for personal and professional Git hosting profiles.
- Use SSH configuration hosts mapping rules to manage multiple accounts without credentials clash.
Frequently Asked Questions (FAQ)
Q: Can I use HTTPS instead?
Yes. Instead of SSH (git@github.com:user/project.git), you can update the remote URL to use HTTPS: 'git remote set-url origin https://github.com/user/project.git'.
Q: How do I check my SSH key?
Run 'ls -la ~/.ssh' to list all files inside your SSH directory and see if keys like id_ed25519 or id_rsa exist.
Q: How do I see loaded SSH keys?
Run 'ssh-add -l' to view all keys currently loaded in your active SSH agent session.
Q: Can one SSH key work for multiple repositories?
Yes. As long as the repositories belong to the same Git account, the same public key can authorize access for all of them.