SSH Troubleshooting

This page shows common problems experienced with SSH in general, and when establishing an SSH tunnel, and solutions for each problem.

Tip: Most port-forwarding problems are caused by a basic misunderstanding of how an SSH tunnel actually works, so it is highly recommended that you read the SSH Tunnel page before continuing.

Table of Contents

Connection Problems

Unable to open connection: Host does not exist

Connection fails with the following error:
Unable to open connection:
Host does not exist
This error occurs when:
  • The server name cannot be resolved to an IP address. If it could be, a different error would be displayed (such as Connection refused). Check the server exists and is reachable using PING.
ping servername

Unable to open connection: gethostbyname: unknown error

Connection fails with the following error:
Unable to open connection:
gethostbyname: unknown error
This error occurs when:

Connection refused

Connection fails with the following error:
Failed to connect to Network error: Connection refused
Network error: Connection refused
FATAL ERROR: Network error: Connection refused

This error occurs when:

  • The server name is incorrect. Verify the server exists and is running SSHD.
  • The port specified with the -P (PLINK/PuTTY) or -p (ssh) argument is incorrect. Verify that the port is correct.
  • There is a firewall or other connection problem between the two servers. Try using telnet to telnet to the server/port.

Failed to add the host to the list of known hosts (/home/USERNAME/.ssh/known_hosts)

Connection works, but the following warning is issued
Failed to add the host to the list of known hosts (/home/USERNAME/.ssh/known_hosts)

This error occurs when:

  • The user's HOME folder has incorrect permissions
  • The user's HOME/.ssh folder or HOME/.ssh/known_hosts file has incorrect permissions (such as when the folder has been copied into location by root, or permissions have been manually set incorrectly)

To fix, execute these commands (as root) to reset the permissions to their correct values (replace USERNAME with the appropriate username)

cd ~
chown USERNAME /home/username
chown USERNAME -R /home/username/.ssh
chmod 700 /home/USERNAME/.ssh
chmod 600 /home/USERNAME/.ssh/*

Authentication Problems

When using a key, you are prompted for a password (instead of automatically authenticating)

This can be caused be:

  • Providing a passphrase on the key. Verify that you have created the SSH key-pair with no passphrase
  • Incorrect setup on the SSH server (key file or security not correctly configured). In some cases, no error will appear in the SSHD logs on the server.
  • Incorrect key specified on the client. For example, specifying the public key in the command line arguments instead of the private key.
  • Incorrect username specified for the key. For example, the key has been installed for user "neale" but you are connecting as username "cassie".

Unable to use key file "keys\KEYNAME.ppk" (unable to open file)

This is caused by an inability to open the specified SSH key file.

  • Verify that the key file exists, and is really at the location you have specified with the -i argument
  • Verify that the local user executing the PLINK/ssh command has permissions to read the key file

Tunnel Problems / Port Forwarding Problems

Note that some of these errors will only appear if verbose-output (-v) is switched on for the PLINK command or SSH commands. PuTTY hides them, but PLINK can be used with exactly the same command line arguments, so test with PLINK and the -v command line option.

Forwarded connection refused by server: Administratively prohibited [open failed], or channel N: open failed: administratively prohibited: open failed

This error appears in the PLINK/PuTTY/ssh window when:

  • the port forwarding address does not exist (most common reason, normally a typo)
  • port-forwarding has been disabled server-wide in /etc/ssh/sshd_config using AllowTcpForwarding no (default setting is yes)
  • port-forwarding is limited to specific hosts only (and the one you are connecting to is not in the list), in the server-wide setting file /etc/ssh/sshd_config under the PermitOpen option. Note that even if the host is allowed in permitopen in authorized_keys2 (see below), it still needs to be allowed in sshd_config as well.
  • you are using a certificate-based connection and port-forwarding has been disabled in /home/username/.ssh/authorized_keys2 with the option no-port-forwarding
  • you are using a certificate-based connection and port-forwarding is limited to specific hosts only (and the one you are connecting to is not in the list), in the /home/username/.ssh/authorized_keys2 file using the permitopen= option
  • a DNS problem on the server is preventing the host name from being resolved to an IP address (error in DNS, or manual entry in /etc/hosts)

For example, you have tried to connect to using an SSH command line argument such as:

However, does not exist, is not permitted, or cannot be resolved correctly by the remote server. Unfortunately, the error message is quite vague, and always makes it look like a security issue. Verify the server name is correct and try again, then check with your administrator.

When this is the problem the following will appear in the SSH server logs (eg: /var/log/auth.log in Linux):

Nov 28 17:00:57 server sshd[27850]: error: connect_to unknown host (Name or service not known)


Aug 26 17:48:10 server sshd[24180]: Received request to connect to host port NNNN, but the request was denied.

Forwarded connection refused by server: Connect failed [Connection refused]

This error appears in the PLINK/PuTTY/ssh window, when you try to establish a connection to the tunnel, and the server cannot connect to the remote port specified.

For example, you have specified that the tunnel goes to using an SSH command line argument such as:

When you then try to telnet to on the client machine, this is tunnelled through to the server, which then attempts to connect to However, that that connection between the server and is refused.

Check the tunnel server:port is correct, or ensure that the server is able to connect to the specified server:port.

Service lookup failed for destination port ""

This error appears in the PLINK/PuTTY/ssh window, if your tunnel definition is incomplete or incorrect.

For example, the additional space after "3500:" in the following line will cause this error:

line which causes error:
correct line:

Local port forwarding to nnn.nnn.nnn.nnn:nnnnn failed: Network error: Permission denied

This error appears in the PLINK/PuTTY/ssh window, if your PuTTY client cannot listen on the local port you have specified.

This normally occurs because of another service already running on that port.

For example, the tunnel below will fail if you have a local version of SQL/Server already listening on port 1433:


To fix, close the program that is listening on that port (ie: SQL/Server in the example above).

Advanced: You can also adjust to tunnel from another port, such as or However, with SQL/Server, the Management Console application will only allow connections to 1433. Additionally, it listens on, preventing use of port 1433 on any other IP address. Therefore, unless you first adjust the SQL/Server registry settings to listen on a specific IP first, it is not possible to have SQL/Server running at the same time as a local tunnel.

<some program>: not found

If you have connected successfully, but get errors when you try to enter commands at the tunnel prompt, this is because you have access to the tunnel itself, but not to an SSH prompt or any tools on the server. You should not be running these commands at the SSH prompt itself.

Example errors:

  • createuser: not found
  • mysql: not found

If you were trying to establish an SSH tunnel, you have already accomplished this part. Your tunnel should be listening on<some port>. The commands you are trying to execute should be performed in a new Command Prompt or Shell.

Remember - the tunnel is providing access to a remote service, on your local machine, as if the server is your own computer.

You can therefore use any command line or GUI tools at your disposal, and connect directly to<whatever port>.

If you are confused about how this works, see the SSH Tunnel page for diagrams and a full explanation.

See Also

Problem not found / not solved? Something to add?

  • If your problem is not solved by the above guide, please click Add Comment and specify the error message or problem you are having. This will allow us improve this guide.
  • If you have helpful information to add, please feel free to add a comment or register so that you can edit this page yourself.


I do

> ssh -L 873:myotherhost:873 myusername@myotherhost

as root. This connects just fine. myotherhost is running an rsync server which also seems to work fine.


> rsync -vvv somefile rsync://localhost:873/someremotefile

times out and

> nmap localhost

does not see 873 as open.

--Geza Bohus, 08-May-2007

Hi Geza,

After the ssh command, port 873 should immediately open. This is because ssh itself opens the port. Can you try adding -v to the ssh command to see if it displays any messages about opening port 873 during initialisation, then use netstat directly afterwards to see if the port has been opened?

eg: netstat -pant (instead of nmap, which is more useful for port scans)

Also check on the server, in /var/log/syslog and see if any messages appear either after the ssh command, or after the rsync command. If the port opens locally after ssh, but then cannot be established on the server, the error message should appear in the servers syslog.

--Neale Rudd, 08-May-2007

Hi Neale,

Thanks for your comments/advice. I'll check these things and write down my experiences.


--Geza Bohus, 09-May-2007

Hi Neale,

The port is indeed open now, although I haven't consiously changed anything except the -v in the ssh command.

It seems that I have problems using the rsync server, not the tunnel itself.

Thanks again for your help.

--Geza Bohus, 09-May-2007

Hi Geza,

Now that port 873 is open, you should be able to telnet to it with: telnet localhost 873

SSH will accept the connection, and tunnel it through to the server on port 22 (SSH). The server will accept the information through the tunnel on port 22, and then try to open a connection to myotherhost:873. When it attempts this connection, it sounds like something is failing. Therefore the next step would be to confirm that port 873 is open on the server as well. If it is open, but only listening on (ie: it's own localhost), then your ssh command would need to be modified to:

ssh -L 873:localhost:873 myusername@myotherhost

This is actually a shortened version. The full command being used in this case is:

ssh -L localhost:873:localhost:873 myusername@myotherhost

The first localhost:873 is the port to be opened on the client (SSH opens this). The second localhost:873 is the port the server opens when asked to by the client (SSHD opens this).

The most common problem in this case, is that your RSYNC server on the server (myotherhost) is only listening on localhost ( Therefore if you have 873:myotherhost:873, you are telling the server to try and connect to "myotherhost", which will fail.

Let me know if that solves the problem.

--NealeRudd, 10-May-2007

Hi Neale,

I just realized you wrote one more comment. Thanks for your help, everything is working now.


--Geza Bohus, 07-Jun-2007

metawerx specific

referring pages