Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Security and hardening

ssh-agent will not start or Git cannot use your SSH key

ErrorError: ssh-add: illegal option -- apple-use-keychain

Short 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.

  • Applies to OpenSSH 9.x and 10.x, Windows 11 OpenSSH, macOS 15 and later, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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_SOCK
  2. 2Match what you see, then jump to its fix

    1. 1ssh-add exits with status 2 and SSH_AUTH_SOCK is empty.No agent was started in this shellFix
    2. 2ssh-add cannot contact an agent on Windows even though OpenSSH is installed.The Windows ssh-agent service is disabledFix
    3. 3Error: 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. 4Agent admitted failure to sign using the key.The agent runs but cannot sign with the key (Linux)Fix

What does the error look like?

  • Error: ssh-add: illegal option -- apple-use-keychain
  • Bad configuration option: usekeychain
  • Agent 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_ed25519

3Verify

The agent lists your key.

ssh-add -l

Confirmed by man.openbsd.org

Did this fix it?

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-agent

2Fix

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_ed25519

3Verify

The service shows Running and the key is listed.

Get-Service ssh-agent
ssh-add -l

Confirmed by learn.microsoft.com

Did this fix it?

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-add

2Fix

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_ed25519

3Verify

The key is listed and Git no longer asks for the passphrase.

ssh-add -l

Confirmed by docs.github.com

Did this fix it?

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 -l

2Fix

Start a plain ssh-agent and load the key into it.

eval "$(ssh-agent -s)"
ssh-add

3Verify

Test the connection.

ssh -T git@github.com

Confirmed by docs.github.com

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.