ssh-agent will not start or Git cannot use your SSH key
Error: ssh-add: illegal option -- apple-use-keychainShort answer
ssh-add and ssh can only use the agent when SSH_AUTH_SOCK points at a running one. Start it in the same shell with eval, enable the ssh-agent service on Windows (it is disabled by default), and use Apple's own ssh-add on macOS. Then load the key with ssh-add and list it with ssh-add -l.
Fix it fast
1Find out which cause you have
Ask the agent what it holds. Exit status 2 means ssh-add could not reach an agent at all; a list means the agent is fine and the key is the problem.
ssh-add -l -E sha256 echo "exit status: $?" echo $SSH_AUTH_SOCK2Match what you see, then jump to its fix
- 1
ssh-add exits with status 2 and SSH_AUTH_SOCK is empty.No agent was started in this shellFix - 2
ssh-add cannot contact an agent on Windows even though OpenSSH is installed.The Windows ssh-agent service is disabledFix - 3
Error: ssh-add: illegal option -- apple-use-keychain, or Bad configuration option: usekeychain.macOS runs a third-party ssh-add or ssh that lacks Keychain optionsFix - 4
Agent admitted failure to sign using the key.The agent runs but cannot sign with the key (Linux)Fix
- 1
What does the error look like?
Error: ssh-add: illegal option -- apple-use-keychainBad configuration option: usekeychainAgent admitted failure to sign using the key.
Cause 1 of 4
No agent was started in this shell
1Check
ssh-agent prints shell commands that set SSH_AUTH_SOCK and SSH_AGENT_PID. Running it without eval prints them but changes nothing in your shell.
echo "$SSH_AUTH_SOCK $SSH_AGENT_PID"2Fix
Start the agent with eval so the variables land in the current shell, then add the key.
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed255193Verify
The agent lists your key.
ssh-add -lConfirmed by man.openbsd.org
Cause 2 of 4
The Windows ssh-agent service is disabled
1Check
On Windows the ssh-agent service is disabled by default. Check its status in PowerShell.
Get-Service ssh-agent2Fix
In an elevated PowerShell set the service to start automatically and start it, then add the key from a normal terminal.
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\id_ed255193Verify
The service shows Running and the key is listed.
Get-Service ssh-agent
ssh-add -lConfirmed by learn.microsoft.com
Cause 3 of 4
macOS runs a third-party ssh-add or ssh that lacks Keychain options
1Check
An ssh-add from MacPorts or Homebrew earlier in PATH does not know the Apple flag. Find out which one runs.
which -a ssh-add2Fix
Call Apple's binary directly. If ssh itself rejects UseKeychain in your config, tell it to ignore the unknown option.
/usr/bin/ssh-add --apple-use-keychain ~/.ssh/id_ed25519
# ~/.ssh/config
Host github.com
IgnoreUnknown UseKeychain
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_ed255193Verify
The key is listed and Git no longer asks for the passphrase.
ssh-add -lConfirmed by docs.github.com
Cause 4 of 4
The agent runs but cannot sign with the key (Linux)
1Check
GitHub links this on Linux to a known gnome-keyring bug combined with the key not being loaded into the agent.
ssh-add -l2Fix
Start a plain ssh-agent and load the key into it.
eval "$(ssh-agent -s)"
ssh-add3Verify
Test the connection.
ssh -T git@github.comConfirmed by docs.github.com
How do I stop it coming back?
- Put AddKeysToAgent yes in the Host block so the key loads on first use.
- On Windows, set the service to Automatic once, instead of starting it by hand.
- Keep Apple's /usr/bin tools ahead of other ssh builds in PATH on a Mac if you use the Keychain.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Security
AuthenticationException: your certificate validation callback returned false
System.Security.Authentication.AuthenticationException
This message means a validation callback was installed, yours or one a library added, and it returned false.
3 causes, each with a fixSecurity
SSH to an EC2 instance fails with Permission denied (publickey,gssapi-keyex,gssapi-with-mic)
ec2-user@ec2-203-0-113-25.compute-1.amazonaws.com: Permission denied (publickey).
On EC2 this error almost always means the instance did not accept your key for that user.
3 causes, each with a fixSecurity
gcloud init cannot finish the sign-in step
Enter authorization code
gcloud init signs in through a browser.
3 causes, each with a fixSecurity
A GitHub Actions SSH deploy step cannot log in to the server
ssh: handshake failed: ssh: unable to authenticate
The runner reached your server but the server refused the login.
4 causes, each with a fixSecurity
SSH to GitHub asks to confirm the host, or hangs on that prompt
ED25519 key fingerprint is SHA256:
SSH has never seen github.com from this machine, so it asks you to trust the server key.
2 causes, each with a fixSecurity
A GUI program over SSH says it cannot open the display
cannot open display:
ssh must forward X11 and the remote sshd must allow it.
3 causes, each with a fix