ssh-add: illegal option -- apple-use-keychain, or Bad configuration option: UseKeychain, on a Mac
Frank Zhang
- 4 minutes read - 1735 wordsTL;DR
Apple’s Keychain flags exist on /usr/bin/ssh and /usr/bin/ssh-add. Read which -a and the version lines, call /usr/bin/ssh-add by path, and treat IgnoreUnknown as a way to hide an unknown option.
Match one of these two lines before you change PATH, uninstall a package, or delete ~/.ssh. They show up in Terminal on a Mac, and in any program on that Mac that runs ssh or ssh-add:
ssh-add: illegal option -- apple-use-keychain
Bad configuration option: UseKeychain
GitHub titles the first one Error: ssh-add: illegal option – apple-use-keychain. Their page Generating a new SSH key and adding it to the ssh-agent writes the second as Bad configuration option: usekeychain. The keyword in ~/.ssh/config is UseKeychain. OpenSSH’s readconf.c, as read for this page, lowercases the keyword before Bad configuration option:, so the printed word is usekeychain, and that line also names the file and a line number from your copy. This page does not pin the number. Either casing is the same option.
Both lines usually mean the ssh or ssh-add on PATH is not Apple’s. --apple-use-keychain and UseKeychain exist on Apple’s /usr/bin/ssh and /usr/bin/ssh-add. Homebrew, MacPorts, or another OpenSSH build does not implement them, so the flag comes back as illegal option and the config keyword comes back as Bad configuration option. That result is not proof the key is bad, and it is not a reason to delete ~/.ssh.
Nothing on this site records these two lines, and nothing records a which -a or ssh -V reading for them. What follows is general guidance, plus GitHub’s pages and the manuals. These commands were not re-run on a Mac for this page. macOS ships its own OpenSSH. If man on the machine in front of you disagrees, that copy wins. If GitHub edits a quoted line, the doc page wins.
If the sentence on screen is Permission denied (publickey), start with Permission denied (publickey) for git@github.com on a Mac: the server refused every offered key. That page already says which ssh-add to use after the fingerprint read agrees. This page is only what happens when those Keychain steps themselves error.
Thirty seconds
| Text on screen | What it means here | First read-only command |
|---|---|---|
ssh-add: illegal option -- apple-use-keychain | This ssh-add does not implement Apple’s flag. | which -a ssh-add |
Bad configuration option: UseKeychain, or GitHub’s usekeychain | The ssh that opened ~/.ssh/config does not implement UseKeychain. | which -a ssh |
Permission denied (publickey) | The server refused the user keys that were offered. | The publickey article linked above. |
Read which binary, before you edit anything
These three commands do not write ~/.ssh/config, do not add a key, and do not remove a package:
which -a ssh ssh-add
ssh -V
/usr/bin/ssh -V
which -a prints every match on PATH, in the order the shell searches. The first line for each name is the binary a bare ssh or ssh-add runs. The first ssh and the first ssh-add can sit in different prefixes. Read the line for the command that just failed.
The lines you want, once the next step uses Apple’s Keychain flags, are /usr/bin/ssh and /usr/bin/ssh-add. GitHub’s generating page says to add the key with the default macOS ssh-add, not one installed by MacPorts, Homebrew, or another external source. If /opt/homebrew/bin or /opt/local/bin, or another prefix, is the first line, that shell runs the non-Apple binary. This page does not record a machine that printed /opt/homebrew/bin. Those two prefixes are the usual Homebrew and MacPorts locations. Compare them with the paths your own which -a printed.
ssh -V is the ssh on PATH. /usr/bin/ssh -V is Apple’s build. Different text means a bare ssh is a different build from /usr/bin/ssh. On macOS, Apple’s version line often names LibreSSL, and a Homebrew build often names OpenSSL. That library-name difference is a common pattern, not a version string measured for this page. Trust the text on your machine. ssh -V does not identify ssh-add; use the ssh-add line from which -a for the flag error.
Call Apple’s ssh-add by path
GitHub’s troubleshooting page adds the private key with Apple’s binary:
/usr/bin/ssh-add --apple-use-keychain ~/.ssh/id_ed25519
Replace id_ed25519 when the private key has another name. Their note: --apple-use-keychain is in Apple’s standard ssh-add, and it stores the passphrase in the keychain when you add the key to the agent. In macOS versions prior to Monterey (12.0), use -K instead of --apple-use-keychain.
The generating page uses the same flag without the /usr/bin prefix, for the case where Apple’s ssh-add is already the one on PATH. Drop --apple-use-keychain when the key has no passphrase. The same note says that prior to 12.0, --apple-use-keychain and --apple-load-keychain were -K and -A. --apple-load-keychain (older -A) reloads keys already stored in the keychain. This page did not run it, and it does not record a failure or a success.
A Homebrew or MacPorts ssh can stay installed for ordinary connections. The opening fix is to call /usr/bin/ssh-add by path. Uninstalling that other OpenSSH is an optional later choice, if you want Apple’s ssh to be the first line which prints. It comes after the read above. This page does not record anyone uninstalling it.
Bad configuration option, in two cases
Read which -a ssh before you edit ~/.ssh/config. The same sentence has two common causes. Both are general guidance.
The ssh reading the file is not Apple’s
UseKeychain is Apple’s option. On GitHub’s generating page it stores the passphrase in the keychain, and that page says to omit the line when the key has no passphrase. A non-Apple ssh stops while reading the file, because it does not implement the keyword.
GitHub’s sample for Bad configuration option: usekeychain is an IgnoreUnknown line in the Host github.com block:
Host github.com
IgnoreUnknown UseKeychain
ssh_config(5) says IgnoreUnknown is a pattern-list of unknown options to ignore, and that it should be listed early, because it is not applied to unknown options that appear before it. Put IgnoreUnknown UseKeychain above UseKeychain. The rest of that host block, including which IdentityFile to set, stays on the publickey page. This page does not choose a key.
IgnoreUnknown only suppresses the unknown-option error. It does not add Keychain support to a non-Apple ssh. That binary does not store the passphrase in the keychain, and a later connection with the same ssh does not read one back from there. To use UseKeychain, the ssh that reads the file has to be Apple’s. Call /usr/bin/ssh by path for that work, or put /usr/bin ahead of the other prefix on the PATH you use for it. Ordinary connections can keep the other ssh.
Apple’s archived Technical Note TN2449 shows the same pair, IgnoreUnknown UseKeychain above UseKeychain, for a file shared with an OpenSSH that does not understand the option. The note is about sharing the file. It does not add a keychain to that other ssh.
Linux, Windows, or a CI runner
UseKeychain is specific to Apple’s ssh. A client on Linux, Windows, or a CI image rejects the keyword because that build does not have it. The same sentence shows up off a Mac for that reason. General guidance, in one step: remove the UseKeychain line in those environments, or keep IgnoreUnknown UseKeychain above it so one config file can be copied around. IgnoreUnknown still does not create a keychain on those systems. This page does not walk through Windows OpenSSH or a Linux client.
What to leave alone
- Leave
/opt/homebrew/bin/ssh,/opt/homebrew/bin/ssh-add, and the copies under/opt/local/binwhere they are. GitHub’s documented fix is to call/usr/bin/ssh-addby path. - Leave
~/.sshin place. These errors are about which binary read a flag or a config line. The directory also holds private keys,config, andknown_hosts. - Leave the modes on
~/.sshalone.chmod 777is the wrong direction. A permissions failure is a different sentence, covered on the publickey page. - Read
which -abeforebrew uninstall opensshorport uninstall openssh. Uninstall is optional, and it is a later choice. - Leave unofficial taps alone. A third-party patch that tries to add Keychain support to another OpenSSH is out of scope here, and it is not the fix on GitHub’s page.
- Leave
sudooffssh-add.sudoreads root’s home. Leave System Integrity Protection on. Leave the systemssh-agentin place. The publickey article already covers that split for git andssh. - Leave the private key file, and the public key stored on the GitHub account, to the publickey page. This page does not generate a key and does not ask you to paste one.
Where this page stops
- No
which -alisting and nossh -Vstring from a machine is recorded here. The Monterey (12.0) cutoff for-Kand-Ais the one GitHub documents. Ifmanon the machine disagrees, that copy wins. Permission denied (publickey)stays on that article.WARNING: REMOTE HOST IDENTIFICATION HAS CHANGEDis the host-key layer: check the fingerprint before you edit known_hosts. The known_hosts fix command generator fills in the removal command after that check.ssh: connect to host … port 22: Connection refusedhas not tried a key yet: Connection refused, from a Mac or into a Mac.- A tunnel whose address and port kept changing is a different layer. The Chinese note 一次ssh排错经历 is that tunnel, not these two lines.
- Other paths on the site start at Start Here. The Chinese writeup of this same topic is Mac 上出现 ssh-add: illegal option – apple-use-keychain 或 Bad configuration option: UseKeychain:先看你在用哪一个 ssh.
- Search volume. This page does not add an external measurement.
If this post helps, you can sponsor the blog. This is voluntary personal support, not a charitable donation.