This error occurs when your SSH configuration file (~/.ssh/config) contains an unrecognized or unsupported option. It's typically caused by typos, unsupported options for your SSH version, or platform-specific settings used on an incompatible system.
SSH reads your configuration file (~/.ssh/config) when establishing connections. If a configuration option is not recognized by your version of OpenSSH, SSH stops parsing and reports "Bad configuration option" with the line number. This happens during the config parsing phase, before any connection is attempted. The error message includes the line number where the problem was found, though sometimes it points to the following line, making it important to check context around the reported line.
SSH will show the problematic line number in the error message. For example:
/home/user/.ssh/config: line 42: Bad configuration option: UseKeychainOpen your config file and check line 42 (and the surrounding context):
cat -n ~/.ssh/config | sed -n '40,45p'This will show line numbers, making it easy to spot the problem.
SSH configuration options are case-sensitive and must be spelled exactly right. Common misspellings:
| Wrong | Correct |
|-------|---------|
| IdentiyFile | IdentityFile |
| HostName | HostName (not Hostname) |
| ProxyJump | ProxyJump |
| StrictHostKeyChecking | StrictHostKeyChecking |
| AddKeysToAgent | AddKeysToAgent |
| ServerAliveInterval | ServerAliveInterval |
Review the exact spelling of every option. Use the official SSH documentation as a reference:
man ssh_configSome SSH options are only available in newer versions of OpenSSH. Check your version:
ssh -VThis will show output like: OpenSSH_8.2p1 Ubuntu-4ubuntu0.5
Then check the OpenSSH release notes to see which version added the problematic option. For example:
- UseKeychain was added in OpenSSH 7.3 (macOS specific)
- AddKeysToAgent was added in OpenSSH 7.2
- IgnoreUnknown was added in OpenSSH 7.3
If you're using an older version and need a newer option, either upgrade OpenSSH or remove the unsupported option.
Some options only work on specific platforms:
UseKeychain - macOS only (not available on Linux/Windows)
ControlMaster, ControlPath, ControlPersist - Not supported on Windows native SSH
If you're on Linux/Windows and see these in your config, comment them out or remove them:
# For macOS only:
# UseKeychain yes
# AddKeysToAgent yes
Host example.com
HostName example.com
User myuser
IdentityFile ~/.ssh/id_rsaIf you need different configs for macOS vs Linux, consider using the IgnoreUnknown directive at the top of your config to suppress warnings about unsupported options.
If you maintain a config file across multiple systems (macOS, Linux, Windows), use IgnoreUnknown to ignore unsupported options instead of having them cause errors:
# At the top of ~/.ssh/config
IgnoreUnknown UseKeychain,AddKeysToAgent
# Now these won't cause errors on non-macOS systems
Host example.com
HostName example.com
User myuser
UseKeychain yes
AddKeysToAgent yes
IdentityFile ~/.ssh/id_rsaThe listed options will be silently ignored on systems that don't support them.
Sometimes copy-pasting from websites or documents introduces hidden Unicode characters or mixed line endings. Check your file:
# Show hidden characters and line endings
cat -A ~/.ssh/config | sed -n '40,45p'Lines ending with $ (Unix/Linux) are correct. Lines ending with ^M$ indicate Windows-style line endings (CRLF), which can cause parsing issues.
Fix line endings if needed:
# Convert CRLF to LF
dos2unix ~/.ssh/config
# Or using sed
sed -i 's/\r$//' ~/.ssh/configIf you suspect encoding issues, you can also recreate the problematic lines manually instead of copy-pasting.
Test your SSH config without making a connection using ssh -G:
ssh -G example.comIf your config is valid, this will output the effective configuration for that host. If there are parsing errors, SSH will report them with the line number.
Another validation method:
# This will fail if config is invalid
ssh -T -F ~/.ssh/config example.comOnce the config is valid, ssh will attempt the connection (and may fail for other reasons, but parsing errors are gone).
Review the complete list of valid SSH configuration options:
man ssh_configThis shows all available options, their syntax, and which versions of OpenSSH support them. Pay special attention to:
- Case sensitivity requirements
- Valid values (e.g., yes/no vs true/false)
- Host block vs global scope requirements
Some options only work inside Host blocks, not at the top level of the config file. For example:
# WRONG: Global level
IdentityFile ~/.ssh/id_rsa
# CORRECT: Inside Host block
Host example.com
IdentityFile ~/.ssh/id_rsaAdvanced troubleshooting:
Version-specific options: Different OpenSSH versions support different options. Use ssh -V to check your version and cross-reference the man pages for that version. For example, OpenSSH 8.8+ changed some behavior around public key authentication.
Distribution-specific patches: Some Linux distributions (Ubuntu, Fedora, CentOS) apply custom patches to OpenSSH that add or remove options. Check your distribution's OpenSSH documentation if an option seems valid but doesn't work.
SSH Agent integration: The AddKeysToAgent and IdentitiesOnly options interact with ssh-agent in complex ways. If using these, ensure your SSH agent is running (eval $(ssh-agent)) and keys are properly loaded (ssh-add ~/.ssh/id_rsa).
ProxyJump vs ProxyCommand: Older OpenSSH versions don't support ProxyJump. Use ProxyCommand instead:
# Modern (7.3+):
ProxyJump jumphost.com
# Fallback for older versions:
ProxyCommand ssh -W %h:%p jumphost.comWindows OpenSSH: Windows 10+ includes built-in OpenSSH, but it's often outdated. Use ssh -V and consider upgrading or using git-bash/WSL for newer OpenSSH versions with more options.
Load key "/home/user/.ssh/id_rsa": invalid format
How to fix 'Load key invalid format' in SSH
Bad owner or permissions on /home/user/.ssh/config
How to fix "Bad owner or permissions on .ssh/config" in SSH
Error connecting to agent: Connection refused
How to fix "Error connecting to agent: Connection refused" in SSH
Connection closed by UNKNOWN port 65535
How to fix 'Connection closed by UNKNOWN port 65535' in SSH
Offending ECDSA key in /home/user/.ssh/known_hosts:line
How to fix "Offending ECDSA key in known_hosts" in SSH