git clone stops on the UseKeychain line of ~/.ssh/config
Bad configuration option: usekeychainShort answer
UseKeychain is a macOS-style option that your ssh program does not recognise, so it stops while reading ~/.ssh/config and Git cannot connect. Put IgnoreUnknown UseKeychain as the very first line of the file, because it only covers options that come after it. If the key has no passphrase, delete the UseKeychain line.
Fix it fast
1Find out which cause you have
Make ssh read its config on its own, which shows the same error without involving Git, then list where the UseKeychain and IgnoreUnknown lines sit in the file.
ssh -V ssh -G github.com > /dev/null grep -n -i -E "usekeychain|ignoreunknown" ~/.ssh/config2Match what you see, then jump to its fix
- 1
The error appears on Windows (Git Bash), on Linux, or on any machine where the config file was copied from a Mac setup guide.This ssh program does not know the UseKeychain optionFix - 2
The file already contains IgnoreUnknown UseKeychain and the same error keeps coming back.IgnoreUnknown is in the file, but below the line that failsFix - 3
ssh-add loads the key without asking for a passphrase, yet the config contains UseKeychain yes.The key has no passphrase, so the Keychain line is not neededFix
- 1
What does the error look like?
Bad configuration option: usekeychainfatal: Could not read from remote repository.
Cause 1 of 3
This ssh program does not know the UseKeychain option
1Check
GitHub's guide shows UseKeychain only in its macOS instructions, and the OpenSSH manual page for ssh_config does not list it. An ssh program that lacks Apple's addition treats the line as an unknown keyword and stops.
ssh -V
grep -n -i "usekeychain" ~/.ssh/config2Fix
Tell ssh to ignore that one unknown keyword. Put the line at the top of the file, above every Host block.
# first line of ~/.ssh/config
IgnoreUnknown UseKeychain
Host github.com
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_ed255193Verify
ssh reads the file without printing the error and exits with status 0.
ssh -G github.com > /dev/null
echo "exit status: $?"Confirmed by docs.github.com
Cause 2 of 3
IgnoreUnknown is in the file, but below the line that fails
1Check
The manual says IgnoreUnknown is not applied to unknown options that appear before it. Compare the line numbers that the grep from the first step prints: the IgnoreUnknown line must have the smaller number.
grep -n -i -E 'usekeychain|ignoreunknown' ~/.ssh/config2Fix
Move IgnoreUnknown above the first UseKeychain, ideally to line 1. Keep every name on one IgnoreUnknown line, separated by commas, because for each keyword the first value that ssh reads is the one it uses.
# line 1 of ~/.ssh/config (add more unknown names after a comma if you need them)
IgnoreUnknown UseKeychain3Verify
The grep now shows IgnoreUnknown on a lower line number than UseKeychain, and ssh -G finishes cleanly.
grep -n -i -E 'usekeychain|ignoreunknown' ~/.ssh/config
ssh -G github.com > /dev/null && echo "config parses"Confirmed by man.openbsd.org
Cause 3 of 3
The key has no passphrase, so the Keychain line is not needed
1Check
GitHub's own steps say to leave out the UseKeychain line when you chose not to add a passphrase to the key. Try loading the key; if no passphrase is asked, the line has nothing to store.
ssh-add ~/.ssh/id_ed255192Fix
Delete the UseKeychain line and keep the rest of the block.
Host github.com
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed255193Verify
ssh -G reads the file without an error, and the clone connects.
ssh -G github.com > /dev/null && echo "config parses"
git ls-remote git@github.com:OWNER/REPO.gitConfirmed by docs.github.com
How do I stop it coming back?
- When a config file is shared between a Mac and other systems, start it with an IgnoreUnknown line for every Apple-only keyword.
- Run ssh -G on a host name after every edit of ~/.ssh/config: it reports a bad line before Git does.
- Copy a guide's config block only after checking that the guide is written for your operating system.
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
ssh-agent will not start or Git cannot use your SSH key
Bad configuration option: usekeychain
ssh-add and ssh can only use the agent when SSH_AUTH_SOCK points at a running one.
4 causes, each with a fixSecurity
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 fix