How to fix /home/user/.ssh/config: line X: Bad configuration option: in SSH

SSH will show the problematic line number in the error message. For example:

/home/user/.ssh/config: line 42: Bad configuration option: UseKeychain

Open 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_config

Some SSH options are only available in newer versions of OpenSSH. Check your version:

ssh -V

This 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_rsa

If 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_rsa

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

If 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.com

If 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.com

Once 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_config

This 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_rsa