1 \define{versioniderrors} \versionid $Id$
3 \C{errors} Common \i{error messages}
5 This chapter lists a number of common error messages which PuTTY and
6 its associated tools can produce, and explains what they mean in
9 We do not attempt to list \e{all} error messages here: there are
10 many which should never occur, and some which should be
11 self-explanatory. If you get an error message which is not listed in
12 this chapter and which you don't understand, report it to us as a
13 bug (see \k{feedback}) and we will add documentation for it.
15 \H{errors-hostkey-absent} \q{The server's host key is not cached in
18 \cfg{winhelp-topic}{errors.hostkey.absent}
20 This error message occurs when PuTTY connects to a new SSH server.
21 Every server identifies itself by means of a host key; once PuTTY
22 knows the host key for a server, it will be able to detect if a
23 malicious attacker redirects your connection to another machine.
25 If you see this message, it means that PuTTY has not seen this host
26 key before, and has no way of knowing whether it is correct or not.
27 You should attempt to verify the host key by other means, such as
28 asking the machine's administrator.
30 If you see this message and you know that your installation of PuTTY
31 \e{has} connected to the same server before, it may have been
32 recently upgraded to SSH protocol version 2. SSH protocols 1 and 2
33 use separate host keys, so when you first use \i{SSH-2} with a server
34 you have only used SSH-1 with before, you will see this message
35 again. You should verify the correctness of the key as before.
37 See \k{gs-hostkey} for more information on host keys.
39 \H{errors-hostkey-wrong} \q{WARNING - POTENTIAL SECURITY BREACH!}
41 \cfg{winhelp-topic}{errors.hostkey.changed}
43 This message, followed by \q{The server's host key does not match
44 the one PuTTY has cached in the registry}, means that PuTTY has
45 connected to the SSH server before, knows what its host key
46 \e{should} be, but has found a different one.
48 This may mean that a malicious attacker has replaced your server
49 with a different one, or has redirected your network connection to
50 their own machine. On the other hand, it may simply mean that the
51 administrator of your server has accidentally changed the key while
52 upgrading the SSH software; this \e{shouldn't} happen but it is
53 unfortunately possible.
55 You should contact your server's administrator and see whether they
56 expect the host key to have changed. If so, verify the new host key
57 in the same way as you would if it was new.
59 See \k{gs-hostkey} for more information on host keys.
61 \H{errors-portfwd-space} \q{Out of space for port forwardings}
63 PuTTY has a fixed-size buffer which it uses to store the details of
64 all \i{port forwardings} you have set up in an SSH session. If you
65 specify too many port forwardings on the PuTTY or Plink command line
66 and this buffer becomes full, you will see this error message.
68 We need to fix this (fixed-size buffers are almost always a mistake)
69 but we haven't got round to it. If you actually have trouble with
70 this, let us know and we'll move it up our priority list.
72 \H{errors-cipher-warning} \q{The first cipher supported by the server is
73 ... below the configured warning threshold}
75 This occurs when the SSH server does not offer any ciphers which you
76 have configured PuTTY to consider strong enough. By default, PuTTY
77 puts up this warning only for \ii{single-DES} and \i{Arcfour} encryption.
79 See \k{config-ssh-encryption} for more information on this message.
81 \H{errors-toomanyauth} \q{Server sent disconnect message type 2
82 (SSH_DISCONNECT_PROTOCOL_ERROR): "Too many authentication failures for root"}
84 This message is produced by an \i{OpenSSH} (or \i{Sun SSH}) server if it
85 receives more failed authentication attempts than it is willing to
86 tolerate. This can easily happen if you are using Pageant and have a
87 large number of keys loaded into it. This can be worked around on the
88 server by disabling public-key authentication or (for Sun SSH only) by
89 increasing \c{MaxAuthTries} in \c{sshd_config}. Neither of these is a
90 really satisfactory solution, and we hope to provide a better one in a
91 future version of PuTTY.
93 \H{errors-memory} \q{\ii{Out of memory}}
95 This occurs when PuTTY tries to allocate more memory than the system
96 can give it. This \e{may} happen for genuine reasons: if the
97 computer really has run out of memory, or if you have configured an
98 extremely large number of lines of scrollback in your terminal.
99 PuTTY is not able to recover from running out of memory; it will
100 terminate immediately after giving this error.
102 However, this error can also occur when memory is not running out at
103 all, because PuTTY receives data in the wrong format. In SSH-2 and
104 also in SFTP, the server sends the length of each message before the
105 message itself; so PuTTY will receive the length, try to allocate
106 space for the message, and then receive the rest of the message. If
107 the length PuTTY receives is garbage, it will try to allocate a
108 ridiculous amount of memory, and will terminate with an \q{Out of
111 This can happen in SSH-2, if PuTTY and the server have not enabled
112 encryption in the same way (see \k{faq-outofmem} in the FAQ). Some
113 versions of \i{OpenSSH} have a known problem with this: see
114 \k{faq-openssh-bad-openssl}.
116 This can also happen in PSCP or PSFTP, if your \i{login scripts} on the
117 server generate output: the client program will be expecting an SFTP
118 message starting with a length, and if it receives some text from
119 your login scripts instead it will try to interpret them as a
120 message length. See \k{faq-outofmem2} for details of this.
122 \H{errors-internal} \q{\ii{Internal error}}, \q{\ii{Internal fault}},
123 \q{\ii{Assertion failed}}
125 Any error beginning with the word \q{Internal} should \e{never}
126 occur. If it does, there is a bug in PuTTY by definition; please see
127 \k{feedback} and report it to us.
129 Similarly, any error message starting with \q{Assertion failed} is a
130 bug in PuTTY. Please report it to us, and include the exact text
131 from the error message box.
133 \H{errors-cant-load-key} \q{Unable to use this private key file},
134 \q{Couldn't load private key}, \q{Key is of wrong type}
136 \cfg{winhelp-topic}{errors.cantloadkey}
138 Various forms of this error are printed in the PuTTY window, or
139 written to the PuTTY Event Log (see \k{using-eventlog}) when trying
140 public-key authentication, or given by Pageant when trying to load a
143 If you see one of these messages, it often indicates that you've tried
144 to load a key of an inappropriate type into PuTTY, Plink, PSCP, PSFTP,
147 You may have specified a key that's inappropriate for the connection
148 you're making. The SSH-1 and SSH-2 protocols require different private
149 key formats, and a SSH-1 key can't be used for a SSH-2 connection (or
152 Alternatively, you may have tried to load an SSH-2 key in a \q{foreign}
153 format (OpenSSH or \cw{ssh.com}) directly into one of the PuTTY tools,
154 in which case you need to import it into PuTTY's native format
155 (\c{*.PPK}) using PuTTYgen - see \k{puttygen-conversions}.
157 \H{errors-refused} \q{Server refused our public key} or \q{Key
160 Various forms of this error are printed in the PuTTY window, or
161 written to the PuTTY Event Log (see \k{using-eventlog}) when trying
162 public-key authentication.
164 If you see one of these messages, it means that PuTTY has sent a
165 public key to the server and offered to authenticate with it, and
166 the server has refused to accept authentication. This usually means
167 that the server is not configured to accept this key to authenticate
170 This is almost certainly not a problem with PuTTY. If you see this
171 type of message, the first thing you should do is check your
172 \e{server} configuration carefully. Common errors include having
173 the wrong permissions or ownership set on the public key or the
174 user's home directory on the server. Also, read the PuTTY Event Log;
175 the server may have sent diagnostic messages explaining exactly what
176 problem it had with your setup.
178 \H{errors-access-denied} \q{Access denied}, \q{Authentication refused}
180 Various forms of this error are printed in the PuTTY window, or
181 written to the PuTTY Event Log (see \k{using-eventlog}) during
184 If you see one of these messages, it means that the server has refused
185 all the forms of authentication PuTTY has tried and it has no further
188 It may be worth checking the Event Log for diagnostic messages from
189 the server giving more detail.
191 This error can be caused by buggy SSH-1 servers that fail to cope with
192 the various strategies we use for camouflaging passwords in transit.
193 Upgrade your server, or use the workarounds described in
194 \k{config-ssh-bug-ignore1} and possibly \k{config-ssh-bug-plainpw1}.
196 \H{errors-crc} \q{Incorrect \i{CRC} received on packet} or \q{Incorrect
197 MAC received on packet}
199 This error occurs when PuTTY decrypts an SSH packet and its checksum
200 is not correct. This probably means something has gone wrong in the
201 encryption or decryption process. It's difficult to tell from this
202 error message whether the problem is in the client, in the server,
205 A known server problem which can cause this error is described in
206 \k{faq-openssh-bad-openssl} in the FAQ.
208 \H{errors-garbled} \q{Incoming packet was garbled on decryption}
210 This error occurs when PuTTY decrypts an SSH packet and the
211 decrypted data makes no sense. This probably means something has
212 gone wrong in the encryption or decryption process. It's difficult
213 to tell from this error message whether the problem is in the client,
214 in the server, or in between.
216 If you get this error, one thing you could try would be to fiddle
217 with the setting of \q{Miscomputes SSH-2 encryption keys} on the Bugs
218 panel (see \k{config-ssh-bug-derivekey2}).
220 Another known server problem which can cause this error is described
221 in \k{faq-openssh-bad-openssl} in the FAQ.
223 \H{errors-x11-proxy} \q{PuTTY X11 proxy: \e{various errors}}
225 This family of errors are reported when PuTTY is doing X forwarding.
226 They are sent back to the X application running on the SSH server,
227 which will usually report the error to the user.
229 When PuTTY enables X forwarding (see \k{using-x-forwarding}) it
230 creates a virtual X display running on the SSH server. This display
231 requires authentication to connect to it (this is how PuTTY prevents
232 other users on your server machine from connecting through the PuTTY
233 proxy to your real X display). PuTTY also sends the server the
234 details it needs to enable clients to connect, and the server should
235 put this mechanism in place automatically, so your X applications
238 A common reason why people see one of these messages is because they
239 used SSH to log in as one user (let's say \q{fred}), and then used
240 the Unix \c{su} command to become another user (typically \q{root}).
241 The original user, \q{fred}, has access to the X authentication data
242 provided by the SSH server, and can run X applications which are
243 forwarded over the SSH connection. However, the second user
244 (\q{root}) does not automatically have the authentication data
245 passed on to it, so attempting to run an X application as that user
246 often fails with this error.
248 If this happens, \e{it is not a problem with PuTTY}. You need to
249 arrange for your X authentication data to be passed from the user
250 you logged in as to the user you used \c{su} to become. How you do
251 this depends on your particular system; in fact many modern versions
252 of \c{su} do it automatically.
254 \H{errors-connaborted} \q{Network error: Software caused connection
257 This is a generic error produced by the Windows network code when it
258 kills an established connection for some reason. For example, it might
259 happen if you pull the network cable out of the back of an
260 Ethernet-connected computer, or if Windows has any other similar
261 reason to believe the entire network has become unreachable.
263 Windows also generates this error if it has given up on the machine
264 at the other end of the connection ever responding to it. If the
265 network between your client and server goes down and your client
266 then tries to send some data, Windows will make several attempts to
267 send the data and will then give up and kill the connection. In
268 particular, this can occur even if you didn't type anything, if you
269 are using SSH-2 and PuTTY attempts a key re-exchange. (See
270 \k{config-ssh-kex-rekey} for more about key re-exchange.)
272 (It can also occur if you are using keepalives in your connection.
273 Other people have reported that keepalives \e{fix} this error for
274 them. See \k{config-keepalive} for a discussion of the pros and cons
277 We are not aware of any reason why this error might occur that would
278 represent a bug in PuTTY. The problem is between you, your Windows
279 system, your network and the remote system.
281 \H{errors-connreset} \q{Network error: Connection reset by peer}
283 This error occurs when the machines at each end of a network
284 connection lose track of the state of the connection between them.
285 For example, you might see it if your SSH server crashes, and
286 manages to reboot fully before you next attempt to send data to it.
288 However, the most common reason to see this message is if you are
289 connecting through a \i{firewall} or a \i{NAT router} which has timed the
290 connection out. See \k{faq-idleout} in the FAQ for more details. You
291 may be able to improve the situation by using keepalives; see
292 \k{config-keepalive} for details on this.
294 Note that Windows can produce this error in some circumstances without
295 seeing a connection reset from the server, for instance if the
296 connection to the network is lost.
298 \H{errors-connrefused} \q{Network error: Connection refused}
300 This error means that the network connection PuTTY tried to make to
301 your server was rejected by the server. Usually this happens because
302 the server does not provide the service which PuTTY is trying to
305 Check that you are connecting with the correct protocol (SSH, Telnet
306 or Rlogin), and check that the port number is correct. If that
307 fails, consult the administrator of your server.
309 \H{errors-conntimedout} \q{Network error: Connection timed out}
311 This error means that the network connection PuTTY tried to make to
312 your server received no response at all from the server. Usually
313 this happens because the server machine is completely isolated from
314 the network, or because it is turned off.
316 Check that you have correctly entered the host name or IP address of
317 your server machine. If that fails, consult the administrator of
320 \i{Unix} also generates this error when it tries to send data down a
321 connection and contact with the server has been completely lost
322 during a connection. (There is a delay of minutes before Unix gives
323 up on receiving a reply from the server.) This can occur if you type
324 things into PuTTY while the network is down, but it can also occur
325 if PuTTY decides of its own accord to send data: due to a repeat key
326 exchange in SSH-2 (see \k{config-ssh-kex-rekey}) or due to
327 keepalives (\k{config-keepalive}).