How to fix command-line: line 0: Bad configuration option in SSH

SSHBEGINNERMEDIUMUpdated Jan 4, 2026· 311 views

This error occurs when the SSH client or server encounters an invalid or misspelled configuration option. It typically indicates a typo in your SSH config file, use of a deprecated option, or an option that's not supported by your SSH version.

Quick fix

Fixes command-line: line 0: Bad configuration option

# Check your SSH version
ssh -V

# Validate the config file syntax without connecting
ssh -G hostname_or_alias > /dev/null
  1. Check SSH version and validate config syntax
  2. Review the problematic config file line
  3. Fix common typos in option names
  4. Remove macOS-specific options if on Linux/Windows
ssh — error
# Check your SSH version
ssh -V
# Validate the config file syntax without connecting
ssh -G hostname_or_alias > /dev/null
command-line: line 0: Bad configuration option

What this error means

The "Bad configuration option" error appears when OpenSSH parses a configuration file (either ~/.ssh/config for the client or /etc/ssh/sshd_config for the server) and encounters an unrecognized directive. OpenSSH is strict about configuration syntax—it rejects any option it doesn't understand. The error message usually includes a line number pointing to where the invalid option appears. This error can occur when the SSH client reads ~/.ssh/config or when the SSH server reads its main configuration file.

Typical symptoms

  • SSH connection fails immediately with 'Bad configuration option' error
  • Error message shows the line number and file path where the problem occurs
  • SSH works fine on other machines but fails on this one
  • Error appears only when using specific SSH options or config lines
  • Works after commenting out or removing certain config lines
  • SSH command fails even when no connection is attempted (config syntax check)

Common causes

  1. Typo in option name (e.g., 'HostName' spelled as 'hostname' or 'IdentityFile' as 'identifyfile')
  2. Using a deprecated option that's no longer supported in your OpenSSH version
  3. Using macOS-specific options (like 'UseKeychain') on Linux or other operating systems
  4. Using server-side options (like 'PermitRootLogin') in the client config file (~/.ssh/config)
  5. Option name has incorrect capitalization (SSH config options are case-sensitive)
  6. File encoding issue: file contains BOM (Byte Order Mark) or CRLF line endings instead of LF
  7. Extra whitespace or special characters around option names
  8. Incomplete configuration line (missing value or unclosed string)

How to fix "command-line: line 0: Bad configuration option"

1Check SSH version and validate config syntax

First, verify your SSH version and check if your config file has syntax errors:

bash
# Check your SSH version
ssh -V

# Validate the config file syntax without connecting
ssh -G hostname_or_alias > /dev/null

The ssh -G command will print the effective configuration and immediately show any syntax errors. This helps identify the exact line with the problem.

2Review the problematic config file line

The error message should specify the file and line number. Open the config file and check that line:

bash
# For SSH client config (most common)
nano ~/.ssh/config

# For SSH server config (if you're running sshd)
sudo nano /etc/ssh/sshd_config

Look at the line mentioned in the error. Check for:
- Typos in the option name
- Lowercase letters (should be: HostName, IdentityFile, Port, User, etc.)
- Trailing characters or spaces
- Incomplete configuration

3Fix common typos in option names

Verify option names use correct capitalization. Here are common mistakes:

Common typos:
- 'hostname' → should be 'HostName'
- 'identityfile' → should be 'IdentityFile'
- 'user' → should be 'User'
- 'port' → should be 'Port'
- 'identitiesonly' → should be 'IdentitiesOnly'
- 'usekeychain' → should be 'UseKeychain' (macOS only)
- 'identifyfile' → should be 'IdentityFile' (common typo)

Example of correcting ~/.ssh/config:

bash
# WRONG (typo)
Host myserver
  HostName example.com
  IdentityFile ~/.ssh/id_rsa
  identitiesonly yes  # WRONG case

# CORRECT
Host myserver
  HostName example.com
  IdentityFile ~/.ssh/id_rsa
  IdentitiesOnly yes  # CORRECT case
4Remove macOS-specific options if on Linux/Windows

If you're getting 'Bad configuration option: UseKeychain' on Linux or Windows, it's because that option only works on macOS. Handle this in two ways:

Option 1: Use IgnoreUnknown directive (SSH 7.3+)

Add this at the top of ~/.ssh/config to ignore unknown options:

bash
IgnoreUnknown UseKeychain

Host *
  UseKeychain yes
  AddKeysToAgent yes
  IdentityFile ~/.ssh/id_ed25519

The SSH client will silently ignore 'UseKeychain' and 'AddKeysToAgent' on systems that don't support them.

Option 2: Conditionally include config files

Use Include with environment-specific config files:

bash
# ~/.ssh/config

# Include macOS-specific config
Include ~/.ssh/config.macos

# Common settings
Host *
  AddKeysToAgent yes
  IdentityFile ~/.ssh/id_ed25519

Then create ~/.ssh/config.macos with macOS-only options:

bash
Host *
  UseKeychain yes
5Check for deprecated options in your SSH version

Some options have been deprecated and removed in newer OpenSSH versions. Check your SSH version:

bash
ssh -V

Common deprecated options:
- 'RSAAuthentication' (removed in OpenSSH 7.4, use PubkeyAuthentication instead)
- 'DSAAuthentication' (deprecated)
- 'RhostsRSAAuthentication' (deprecated)
- 'GSSAPICleanupCredentials' (changed to GSSAPICleanupcredentials in some versions)

If you see a deprecated option error, check the OpenSSH release notes for your version or remove the option from your config.

6Fix file encoding and line ending issues

Check if the file has incorrect encoding or line endings. This sometimes causes parsing issues:

Using vim to check and fix:

bash
vim ~/.ssh/config
# Type: :set fileformat?

- If output is 'fileformat=dos', the file has CRLF line endings (Windows style)
- Fix by typing: :set fileformat=unix then :wq

Also check for BOM (Byte Order Mark):

bash
# Check for BOM
file ~/.ssh/config

# If it shows "UTF-8 (with BOM)", remove BOM:
# Using vim:
# :set nobomb
# :wq

Using dos2unix tool:

bash
# Convert CRLF to LF
dos2unix ~/.ssh/config
7Ensure no server options are in client config

The client config (~/.ssh/config) and server config (/etc/ssh/sshd_config) have different valid options. Using server options in client config causes this error.

Server-only options (belong in /etc/ssh/sshd_config):
- PermitRootLogin
- StrictModes
- MaxAuthTries
- MaxSessions
- PubkeyAuthentication (server-side)
- PasswordAuthentication (server-side)
- PermitEmptyPasswords

Client-only options (belong in ~/.ssh/config):
- HostName
- User
- IdentityFile
- ProxyCommand
- LocalForward
- RemoteForward

Example mistake:

bash
# WRONG - ~/.ssh/config
Host myserver
  HostName example.com
  PermitRootLogin no  # THIS IS A SERVER OPTION

# CORRECT - ~/.ssh/config
Host myserver
  HostName example.com
  User myuser

# Server option belongs in /etc/ssh/sshd_config instead
8Comment out problematic lines and test incrementally

If you can't identify the exact issue, comment out suspect lines one at a time and test:

bash
# In ~/.ssh/config, comment out lines with #
# Host example
#   HostName example.com
#   IdentityFile ~/.ssh/id_rsa
#   UseKeychain yes  # Try commenting this out first if on Linux

# Test if config now works
ssh -G example > /dev/null && echo "Config OK" || echo "Still has errors"

Once you find the problematic line, fix or remove it. Then uncomment the rest.

Advanced notes

Advanced troubleshooting:

SSH version-specific options: Some options were added in specific OpenSSH versions. Check the man page for your version:

bash
man ssh_config | grep -A 2 "OptionName"

Include directive: Modern OpenSSH (7.3+) supports the Include directive, allowing you to split config into multiple files:

bash
Include ~/.ssh/config.d/*

This is useful for managing platform-specific or project-specific SSH settings.

Debugging SSH config: Use ssh -vvv hostname for verbose output showing exactly which config options are being loaded and how they're interpreted.

Config file permissions: While not directly causing this error, ensure ~/.ssh/config has proper permissions (600) for SSH to accept it:

bash
chmod 600 ~/.ssh/config

Match directive: OpenSSH 6.7+ supports conditional config using Match blocks, allowing you to apply options based on criteria:

bash
Match host example.com
  IdentityFile ~/.ssh/id_rsa

Match host *.local
  StrictHostKeyChecking no

IgnoreUnknown directive usage: While IgnoreUnknown helps with cross-platform compatibility, don't overuse it. Only ignore options you specifically expect on some platforms.

Frequently asked questions

What does "command-line: line 0: Bad configuration option" mean?
ssh/config for the client or /etc/ssh/sshd_config for the server) and encounters an unrecognized directive. OpenSSH is strict about configuration syntax—it rejects any option it doesn't understand. The error message usually includes a line number pointing to where the invalid option appears.
How do I fix "command-line: line 0: Bad configuration option"?
This error occurs when the SSH client or server encounters an invalid or misspelled configuration option. It typically indicates a typo in your SSH config file, use of a deprecated option, or an option that's not supported by your SSH version.
What causes "command-line: line 0: Bad configuration option"?
Typo in option name (e.g., 'HostName' spelled as 'hostname' or 'IdentityFile' as 'identifyfile') Using a deprecated option that's no longer supported in your OpenSSH version Using macOS-specific options (like 'UseKeychain') on Linux or other operating systems
Is the "command-line: line 0: Bad configuration option" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading