Fix: Permission denied (publickey) error

The ‘Permission denied (publickey)’ error occurs when SSH key authentication fails, typically due to incorrect key configuration, wrong permissions, or mismatched public/private key pairs when connecting to Git repositories or remote servers.

---

How the Error Happens

This error typically occurs when:

• SSH key is not properly configured
• Incorrect permissions on SSH key files
• Public key not added to remote server/repository
• Wrong SSH key being used for connection
• SSH agent not running or not managing keys properly

---

Solution 1: Verify SSH Key Generation and Setup

# ✅ Generate SSH key pair if not already done
ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_ed25519

# ✅ Or for RSA (alternative)
ssh-keygen -t rsa -b 4096 -C "your_email@example.com" -f ~/.ssh/id_rsa

# ✅ Set correct permissions for SSH directory
chmod 700 ~/.ssh

# ✅ Set correct permissions for private key
chmod 600 ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_rsa

# ✅ Set correct permissions for public key
chmod 644 ~/.ssh/id_ed25519.pub
chmod 644 ~/.ssh/id_rsa.pub

# ✅ Check if SSH keys exist
ls -la ~/.ssh/

# ✅ Verify key fingerprint matches
ssh-keygen -lf ~/.ssh/id_ed25519.pub

---

Solution 2: Start and Configure SSH Agent

# ✅ Start SSH agent
eval "$(ssh-agent -s)"

# ✅ Add your SSH private key to the agent
ssh-add ~/.ssh/id_ed25519
# OR
ssh-add ~/.ssh/id_rsa

# ✅ Verify keys are added
ssh-add -l

# ✅ Create or edit SSH config file
nano ~/.ssh/config

# ✅ Add configuration for GitHub (example)
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
    PreferredAuthentications publickey

---

Solution 3: Add Public Key to Remote Service

# ✅ Copy public key to clipboard
cat ~/.ssh/id_ed25519.pub
# OR
pbcopy < ~/.ssh/id_ed25519.pub  # On macOS
clip < ~/.ssh/id_ed25519.pub    # On Windows with WSL

# ✅ For GitHub:
# 1. Go to GitHub.com → Settings → SSH and GPG keys
# 2. Click "New SSH key"
# 3. Paste the public key content
# 4. Give it a descriptive title

# ✅ For GitLab:
# 1. Go to GitLab.com → Settings → SSH Keys
# 2. Paste the public key
# 3. Click "Add key"

# ✅ For Bitbucket:
# 1. Go to Bitbucket.org → Settings → SSH Keys
# 2. Add the public key

---

Solution 4: Test SSH Connection

# ✅ Test connection to GitHub
ssh -T git@github.com

# ✅ Test connection to GitLab
ssh -T git@gitlab.com

# ✅ Test connection with verbose output for debugging
ssh -vT git@github.com

# ✅ Test connection with specific key
ssh -i ~/.ssh/id_ed25519 -T git@github.com

---

Solution 5: Fix Git Remote URL

# ❌ If using HTTPS (may cause authentication issues)
git remote -v
# origin  https://github.com/username/repo.git (fetch)

# ✅ Change to SSH URL
git remote set-url origin git@github.com:username/repo.git

# ✅ Verify the change
git remote -v
# origin  git@github.com:username/repo.git (fetch)

# ✅ Clone using SSH instead of HTTPS
git clone git@github.com:username/repo.git

# ✅ Or if already cloned, change the remote URL
cd your-repo
git remote set-url origin git@github.com:username/repo.git

---

Solution 6: Troubleshoot Key Permissions

# ✅ Check file permissions
ls -la ~/.ssh/

# ✅ Fix permissions if needed
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 600 ~/.ssh/config

# ✅ Verify key format
head -n 1 ~/.ssh/id_ed25519.pub
# Should start with: ssh-ed25519 AAAA...
# OR ssh-rsa AAAA...

# ✅ Check for Windows line endings (if key was edited on Windows)
dos2unix ~/.ssh/id_ed25519.pub  # Install dos2unix if needed

---

Solution 7: Use SSH Config for Multiple Accounts

# ✅ Edit SSH config for multiple accounts
nano ~/.ssh/config

# ✅ Add configuration for multiple accounts
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_personal
    IdentitiesOnly yes

Host github-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_work
    IdentitiesOnly yes

Host bitbucket.org
    HostName bitbucket.org
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

# ✅ Use specific host for work repository
git clone git@github-work:company/repo.git

---

Solution 8: Windows-Specific Fixes

# ✅ On Windows with Git Bash, start SSH agent
eval $(ssh-agent -s)

# ✅ Add key to agent
ssh-add ~/.ssh/id_ed25519

# ✅ Or use Windows Credential Manager for HTTPS
git config --global credential.helper manager-core

REM ✅ On Windows Command Prompt
REM Start SSH agent service
sc config ssh-agent start=auto
sc start ssh-agent

REM Add key to Windows SSH agent
ssh-add ~/.ssh/id_ed25519

---

Solution 9: Verify and Debug SSH Connection

# ✅ Check if SSH agent is running
ps aux | grep ssh-agent

# ✅ List identities in agent
ssh-add -l

# ✅ Remove and re-add keys if needed
ssh-add -D  # Remove all keys
ssh-add ~/.ssh/id_ed25519  # Add specific key

# ✅ Test with maximum verbosity
ssh -vvv git@github.com

# ✅ Check SSH known_hosts
cat ~/.ssh/known_hosts | grep github

# ✅ Remove and re-add host if needed
ssh-keygen -R github.com

---

Prevention Tips

1. Use strong keys: Use ed25519 or RSA 4096-bit keys
2. Protect private keys: Set proper file permissions (600)
3. Backup keys: Keep secure backups of your private keys
4. Use SSH config: Configure SSH for easier management
5. Test regularly: Periodically test SSH connections
6. Update keys: Rotate keys periodically for security
7. Use passphrases: Add passphrases to private keys
8. Verify fingerprints: Always verify key fingerprints

---

When to Contact Support

Contact your Git hosting provider when:

• Following all troubleshooting steps still results in authentication errors
• Suspected account or repository access issues
• Need to investigate server-side authentication logs
• Encountering platform-specific configuration issues
• Experiencing account-related access problems