Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Security and hardening

git clone stops on the UseKeychain line of ~/.ssh/config

ErrorBad configuration option: usekeychain

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

  • Applies to OpenSSH 9.x and 10.x, Git for Windows, Git 2.4x, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1The 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. 2The file already contains IgnoreUnknown UseKeychain and the same error keeps coming back.IgnoreUnknown is in the file, but below the line that failsFix
    3. 3ssh-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

What does the error look like?

  • Bad configuration option: usekeychain
  • fatal: 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/config

2Fix

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_ed25519

3Verify

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

Did this fix it?

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/config

2Fix

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 UseKeychain

3Verify

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

Did this fix it?

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_ed25519

2Fix

Delete the UseKeychain line and keep the rest of the block.

Host github.com
    AddKeysToAgent yes
    IdentityFile ~/.ssh/id_ed25519

3Verify

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

Confirmed by docs.github.com

Did this fix it?

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

Next step

Want this handled for good?

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