How to fix unknown option -- in SSH

SSHBEGINNERLOWUpdated Jan 4, 2026· 185 views

SSH unknown option errors occur when an invalid or mistyped command-line flag is passed to the ssh command. This commonly happens due to typos, using double-dashes instead of single-dashes, or trying to use options that don't exist in your SSH version.

Quick fix

Fixes unknown option --

# WRONG - typos in option
ssh -prot 22 user@host.example.com
ssh -kep ~/.ssh/id_rsa user@host.example.com

# CORRECT - proper option names
ssh -p 22 user@host.example.com
ssh -i ~/.ssh/id_rsa user@host.example.com
  1. Check your SSH command for typos
  2. Use single-dashes for short options
  3. Verify option syntax with ssh --help
  4. Check for version-specific options
ssh — error
# WRONG - typos in option
ssh -prot 22 user@host.example.com
ssh -kep ~/.ssh/id_rsa user@host.example.com
# CORRECT - proper option names
ssh -p 22 user@host.example.com
ssh -i ~/.ssh/id_rsa user@host.example.com
unknown option --

What this error means

The SSH client strictly validates all command-line options before attempting to connect. When you pass an unrecognized flag (like a typo or a non-existent option), SSH immediately returns an "unknown option" error and exits without trying to connect. The error message typically includes the problematic option to help you identify the issue. Unlike some command-line tools that accept double-dash options (--), SSH uses single-dash options exclusively.

Typical symptoms

  • SSH command fails immediately with 'unknown option --' message
  • Error appears before any connection attempt is made
  • Works on one system but fails on another (version difference)
  • Similar command worked in the past but now fails
  • Error specifies the exact option that caused the problem

Common causes

  1. Typo in option name (e.g., -prot instead of -p, -kep instead of -i)
  2. Using double-dashes (--) instead of single-dash (-) for short options
  3. Option doesn't exist in your current SSH version
  4. Using scp or sftp option with ssh command (e.g., -P for port instead of -p)
  5. Extra spaces or special characters in the option
  6. Old config file containing deprecated SSH options
  7. Option syntax is wrong (e.g., -p port 22 instead of -p 22)

How to fix "unknown option --"

1Check your SSH command for typos

Review the exact command you're running and look for misspelled options:

bash
# WRONG - typos in option
ssh -prot 22 user@host.example.com
ssh -kep ~/.ssh/id_rsa user@host.example.com

# CORRECT - proper option names
ssh -p 22 user@host.example.com
ssh -i ~/.ssh/id_rsa user@host.example.com

Common typos:
- -prot should be -p (port)
- -kep or -key should be -i (identity file)
- -usr should be -l (login username)
- -hosy should be understood as hostname (not an option)

2Use single-dashes for short options

SSH options must use a single dash (-), not double-dashes (--):

bash
# WRONG - double-dashes not supported by ssh
ssh --port 22 user@host.example.com
ssh --identity ~/.ssh/id_rsa user@host.example.com

# CORRECT - single dash
ssh -p 22 user@host.example.com
ssh -i ~/.ssh/id_rsa user@host.example.com

SSH does not support GNU-style long options. Some tools support both -p and --port, but SSH only accepts the short form.

3Verify option syntax with ssh --help

Check what options are available in your SSH version:

bash
ssh --help

Or view the full manual:

bash
man ssh

Look for your option in the list. If it doesn't appear, either:
1. You have a typo
2. The option doesn't exist in your SSH version
3. You're using the wrong command (scp, sftp, ssh-keygen, etc.)

4Check for version-specific options

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

bash
ssh -V

If you're trying to use an option that requires a newer version:
- Upgrade OpenSSH if possible
- Or use the -o option with the older equivalent:

bash
# Instead of: ssh -J jumphost user@target
# On older SSH: ssh -o ProxyCommand="ssh -W %h:%p jumphost" user@target
5Don't mix up ssh, scp, and sftp options

Different SSH tools use different options. A common mistake:

bash
# WRONG - scp uses -P (capital) for port, not -p
ssh -P 2222 user@host.example.com
scp -p file.txt user@host.example.com  # -p means preserve permissions

# CORRECT - ssh uses -p (lowercase) for port
ssh -p 2222 user@host.example.com

# CORRECT - scp uses -P (capital) for port
scp -P 2222 file.txt user@host.example.com

Remember:
- ssh uses lowercase -p for port
- scp and sftp use uppercase -P for port

6Check SSH config files for deprecated options

If you're connecting without explicit options, check your config files:

bash
cat ~/.ssh/config
cat /etc/ssh/ssh_config

Remove any deprecated or invalid options. Example:

bash
# BAD - unknown options
Host myhost
  Hostname host.example.com
  User ubuntu
  IdentityFile ~/.ssh/id_rsa
  UnknownOption value

# GOOD - only valid options
Host myhost
  Hostname host.example.com
  User ubuntu
  IdentityFile ~/.ssh/id_rsa
  Port 22
  StrictHostKeyChecking accept-new
7Use -o flag for advanced options safely

If you need to pass options that might not be recognized, use the -o flag to test:

bash
# -o allows passing options in config file format
ssh -o "Port=2222" user@host.example.com
ssh -o "IdentityFile=~/.ssh/id_rsa" user@host.example.com

# Multiple -o flags work too
ssh -o "Port=2222" -o "StrictHostKeyChecking=no" user@host.example.com

This way, if the option is invalid, you get a clearer error message from the config parser rather than the command-line parser.

Advanced notes

Advanced troubleshooting:

SSH Config File Format vs Command Line: SSH config files use a different syntax than command-line options. Config files use Port 22 while command line uses -p 22. Common mistake: using --Port 22 on the command line (wrong).

Case Sensitivity: SSH options are case-sensitive on the command line. -P (uppercase) is different from -p (lowercase). However, in SSH config files, option names are case-insensitive.

Option Order Matters for Some Tools: While ssh is generally flexible about option order, some SSH wrappers or scripts may require options before the hostname. Try moving options to the front if you get unexpected errors.

Escaping in Scripts: If running SSH from scripts (bash, Python, etc.), be careful with shell escaping. Quotes and special characters can affect how options are parsed:

bash
# In bash script - careful with quotes
ssh -i "~/.ssh/id_rsa" user@host  # May not expand ~
ssh -i "$HOME/.ssh/id_rsa" user@host  # Better - expands variable

Environment Variables: Some SSH behavior can be controlled via environment variables instead of command-line options. Check man ssh_config for options that can also be set in config files.

Frequently asked questions

What does "unknown option --" mean?
The SSH client strictly validates all command-line options before attempting to connect. When you pass an unrecognized flag (like a typo or a non-existent option), SSH immediately returns an "unknown option" error and exits without trying to connect. The error message typically includes the problematic option to help you identify the issue.
How do I fix "unknown option --"?
SSH unknown option errors occur when an invalid or mistyped command-line flag is passed to the ssh command. This commonly happens due to typos, using double-dashes instead of single-dashes, or trying to use options that don't exist in your SSH version.
What causes "unknown option --"?
Typo in option name (e.g., -prot instead of -p, -kep instead of -i) Using double-dashes (--) instead of single-dash (-) for short options Option doesn't exist in your current SSH version
Is the "unknown option --" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading