This error occurs when the ssh-add command cannot communicate with the SSH agent process. The agent may not be running, the socket file may be missing, or environment variables may be misconfigured. This is a common issue on new terminal sessions or after system restarts.
SSH agent is a background process that manages your SSH keys in memory, eliminating the need to enter passphrases repeatedly. When you run ssh-add, it sends commands to the agent via a Unix socket (on Linux/macOS) or named pipe (on Windows). This error means ssh-add cannot find or communicate with that socket. Either the agent process is not running, the socket file has been deleted, or the SSH_AUTH_SOCK environment variable points to an invalid location.
First, verify whether ssh-agent is actually running in your current session.
On Linux/macOS:
ps aux | grep ssh-agentLook for a line that shows ssh-agent (not grep). If you don't see it, the agent is not running.
Alternatively, check the environment variables:
echo $SSH_AUTH_SOCK
echo $SSH_AGENT_PIDBoth should be set. If they're empty, the agent is not initialized.
On Windows (PowerShell):
Get-Service ssh-agent | Select-Object StatusShould show Running. If it shows Stopped, proceed to Step 2.
If ssh-agent is not running, start it with:
eval "$(ssh-agent -s)"This command:
- Starts ssh-agent in the background
- Sets SSH_AUTH_SOCK and SSH_AGENT_PID environment variables
- Makes them available to all subsequent commands in that shell
You should see output like:
Agent pid 1234Now try ssh-add again:
ssh-add ~/.ssh/id_rsaIt should work. Verify with:
ssh-add -lThis lists all identities currently managed by the agent.
If you're on Windows and the ssh-agent service is stopped, start it.
As a one-time fix (for current session):
Start-Service ssh-agentThen try ssh-add:
ssh-add C:\Users\YourUsername\.ssh\id_rsaTo make it automatic (recommended):
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agentThis sets ssh-agent to start automatically on every reboot, so you won't encounter this issue again.
To avoid this error in future terminal sessions, add the agent initialization to your shell startup file.
For Bash, add this to ~/.bashrc:
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)"
fiFor Zsh, add this to ~/.zshrc:
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)"
fiThen reload your shell:
source ~/.bashrc # or source ~/.zshrcNow every time you open a new terminal, SSH agent will be automatically started if it's not already running.
If the agent is running but ssh-add still fails, check the socket file permissions.
ls -la $SSH_AUTH_SOCKThe socket should be owned by your user with restrictive permissions:
srwx------ 1 youruser staff 0 Jan 4 10:30 /tmp/ssh-XXXXXXXXXX/agent.12345If permissions are wrong, fix them:
chmod 700 $(dirname $SSH_AUTH_SOCK)
chmod 600 $SSH_AUTH_SOCKIf the socket file doesn't exist, restart the agent:
eval "$(ssh-agent -s)"On GNOME Desktop (Ubuntu, Fedora), the display manager may set SSH_AUTH_SOCK to GNOME Keyring instead of ssh-agent, causing conflicts.
Check which agent is active:
echo $SSH_AUTH_SOCK
file $SSH_AUTH_SOCKIf it shows a GNOME Keyring path instead of /tmp/ssh-*/agent.*, that's the problem.
Solution: Start SSH agent in your shell configuration AFTER login. Add to ~/.bashrc or ~/.zshrc:
if [ -S "$SSH_AUTH_SOCK" ]; then
# Check if current SSH_AUTH_SOCK is GNOME Keyring
if file "$SSH_AUTH_SOCK" | grep -q "socket"; then
# It's a real socket, keep it
true
else
# Start our own ssh-agent
eval "$(ssh-agent -s)"
fi
else
eval "$(ssh-agent -s)"
fiThen open a new shell (important: use a shell command, not a GUI shortcut) and test:
ssh-add ~/.ssh/id_rsaOnce SSH agent is running, add your private keys.
Basic usage:
ssh-add ~/.ssh/id_rsaIf your key has a passphrase, you'll be prompted to enter it once. The agent caches it in memory for the session.
Add all keys in ~/.ssh:
ssh-add ~/.ssh/id_*Verify keys are loaded:
ssh-add -lShould list your keys with their fingerprints.
Remove a key from agent (optional):
ssh-add -d ~/.ssh/id_rsaRemove all keys from agent (optional):
ssh-add -DAdvanced troubleshooting:
SSH_ASKPASS and SSH_ASKPASS_REQUIRE: In some environments, these variables are set to prevent interactive prompts. If ssh-add fails silently, check if these are set:
echo $SSH_ASKPASS
echo $SSH_ASKPASS_REQUIREUnset them if they're causing issues:
unset SSH_ASKPASS
unset SSH_ASKPASS_REQUIREDebugging agent communication: To see detailed logs, use:
ssh-add -vvv ~/.ssh/id_rsaThe verbose output shows exactly where the communication fails (e.g., socket not found, permission denied, etc.).
SSH agent socket cleanup: On some systems, stale socket files in /tmp accumulate. If you see many agent processes but ssh-add fails, manually clean up:
pkill -9 ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsaRemote SSH sessions: If you're SSH'd into another machine and can't use ssh-add on that remote machine, you need to forward your local agent. Use -A flag:
ssh -A user@remote-hostThen ssh-add on the remote machine will use your local agent.
Load key "/home/user/.ssh/id_rsa": invalid format
How to fix 'Load key invalid format' in SSH
Bad owner or permissions on /home/user/.ssh/config
How to fix "Bad owner or permissions on .ssh/config" in SSH
Error connecting to agent: Connection refused
How to fix "Error connecting to agent: Connection refused" in SSH
Connection closed by UNKNOWN port 65535
How to fix 'Connection closed by UNKNOWN port 65535' in SSH
Offending ECDSA key in /home/user/.ssh/known_hosts:line
How to fix "Offending ECDSA key in known_hosts" in SSH