Differences
This shows you the differences between the selected revisions of the page.
| messages 2008-02-13 | messages 2024-10-13 (current) | ||
| Line 1: | Line 1: | ||
| - | ====== Error Messages ====== | + | ====== Common Error Messages ====== |
| - | ===== [[connection_refused]] Network error: Connection refused ===== | + | |
| - | You may get this message when connecting to a server for following reasons: | + | |
| - | * You are trying to use WinSCP for a purpose for which it is not designed. [[requirements|WinSCP needs]] a SSH or FTP server to be installed at the other end (on the machine you want to connect to). In particular, you cannot easily use it to connect to another Windows workstation, since Windows does not have an SSH or FTP server included by default. | + | ~~SPLIT~~ |
| - | * You are trying to use [[protocol]] that the server does not support. Particularly you are trying SFTP/SCP (over SSH), but the server supports FTP; or vice versa. Check selected protocol on [[ui_login_session#protocol_group|login dialog]]. | + | |
| - | * The server is running on non-standard port. Please make sure you enter actual port number of [[ui_login_session|login dialog]]. | + | ===== [[host_key]] Continue connecting to an unknown server and add its host key to a cache? ===== |
| - | * You may need to connect through proxy server, but you have not specified one on [[ui_login_proxy|login dialog]]. | + | This message appears when WinSCP connects to a new [[SSH]] server. Every server identifies itself by means of a host key; once WinSCP knows the host key for a server, it will be able to detect if a malicious attacker redirects your connection to another machine. |
| + | |||
| + | &screenshotpict(unknown_hostkey) | ||
| + | |||
| + | If you see this message, it means that WinSCP has not seen this host key before, and has no way of knowing whether it is correct or not. You should attempt to verify the host key by other means, such as asking the machine's administrator. ((&puttydoccite)) | ||
| + | |||
| + | If the [[faq_hostkey|host key fingerprint is correct]], press //Accept// (//Yes// in the older versions). &recent The host key will be stored to cache and you will not be prompted the next time. If you are unsure, want to defer a host key verification until later, but still need to connect now (taking a risk), select //Connect Once// in the down-menu of the //Accept// button (//No// button in the older versions). &recent The host key will not be cached and you will be prompted again the next time. If the fingerprint is not correct or if you do not know the correct fingerprint, press //Cancel// to abort connection. | ||
| + | |||
| + | If you have the correct host key (or its fingerprint) in a digital form, instead of checking the fingerprint manually, you can select //Paste Key// in drop-down menu of //Accept// (//Yes//) &recent button to have WinSCP compare the fingerprint for you, against a fingerprint or a full key stored in the clipboard. The clipboard can contain an %%SHA-256%% or %%MD5%% fingerprint or a full key in ''.pub'' format. | ||
| + | |||
| + | Use //Copy key fingerprints to clipboard// link to copy key fingerprints to clipboard (both in %%SHA-256%% format seen on the message and additionally in %%MD5%% format). | ||
| + | |||
| + | Read more about [[ssh_verifying_the_host_key|verifying host keys]]. | ||
| + | |||
| + | Learn also how to [[scripting#hostkey|accept host key automatically in script]]. | ||
| + | |||
| + | ===== [[security_breach]] Warning -- Potential security breach! ===== | ||
| + | This message, followed by //"The server's host key does not match the one WinSCP has in cache"//, means that WinSCP has connected to the SSH server before, knows what its host key should be, but has found a different one. | ||
| + | |||
| + | You might also get the message, when you have configured WinSCP to trust a certification authority for signing host keys but the actual host key is signed by a different authority. For this scenario follow [[#certified|further below]]. | ||
| + | |||
| + | ==== Plain Host key ==== | ||
| + | |||
| + | The message may mean that a malicious attacker has replaced your server with a different one, or has redirected your network connection to their own machine. On the other hand, it may simply mean that the administrator of your server has accidentally changed the key while upgrading the SSH software; this shouldn't happen but it is unfortunately possible. Another legitimate reason for the host key change is that the address, you are connecting to, load balances to a set of SSH servers. If that's the case, select //Add// to build a list of known host keys, instead of using //Update//. | ||
| + | |||
| + | You should contact your server's administrator and see whether they expect the host key to have changed. If so, verify the new host key in the same way as you would if it was new. ((&puttydoccite)) | ||
| + | |||
| + | Read more about [[ssh_verifying_the_host_key|verifying host keys]]. | ||
| + | |||
| + | ==== [[certified]] Certified Host key ==== | ||
| + | |||
| + | If you've configured WinSCP to trust at least one [[ui_pref_security#authorities|certification authority for signing host keys]], then it will ask the SSH server to send it any available certified host keys. If the server sends back a certified key signed by a different certification authority, WinSCP will present this variant of the host key prompt. | ||
| + | |||
| + | One reason why this can happen is a deliberate attack. Just like an ordinary man-in-the-middle attack which substitutes a wrong host key, a particularly ambitious attacker might substitute an entire wrong certification authority, and hope that you connect anyway. | ||
| + | |||
| + | But it's also possible in some situations that this error might arise legitimately. For example, if your organisation's IT department has just rolled out a new CA key which you haven't yet entered in WinSCP's configuration, or if your CA configuration involves two overlapping domains, or something similar. | ||
| + | |||
| + | So, unfortunately, you'll have to work out what to do about it yourself: make an exception for this specific case, or abandon this connection and install a new CA key before trying again (if you're really sure you trust the CA), or edit your configuration in some other way, or just stop trying to use this server. | ||
| + | |||
| + | If you're convinced that this particular server is legitimate even though the CA is not one you trust, WinSCP will let you cache the certified host key, treating it in the same way as an uncertified one. Then that particular certificate will be accepted for future connections to this specific server, even though other certificates signed by the same CA will still be rejected.((&puttydoccite)) | ||
| + | |||
| + | ===== [[connection_refused]] Network error: Connection to "..." refused =====· | ||
| + | You may get this message when connecting to a server for the following reasons: | ||
| + | * The server is down. Please talk to the server or network administrator. | ||
| + | * You are trying to use WinSCP for a purpose for which it is not designed. [[requirements|WinSCP needs]] an SSH or FTP server to be installed at the other end (on the machine you want to connect to). In particular, you cannot easily use it to connect to another Windows workstation, since Windows does not have an %%SSH%% or %%FTP%% server included by default. Please refer to the guide to [[guide_exchange|exchanging files over Internet]]. | ||
| + | * You are trying to use [[protocols|protocol]] that the server does not support. Particularly you are trying SFTP/SCP (over %%SSH%%), but the server supports %%FTP%%; or vice versa. Check selected protocol on [[ui_login#session_settings|Login dialog]]. Note that WinSCP defaults to %%SFTP%% protocol, while most other similar applications default to %%FTP%%. | ||
| + | * The server is running on a non-standard port. Please make sure you enter actual port number on [[ui_login|Login dialog]]. | ||
| + | * You may need to connect through a proxy server, but you have not specified one on //[[ui_login_proxy|Proxy page]]// of Advanced Site Settings dialog. | ||
| + | * Connection was blocked by the firewall. Please refer to [[faq_connection_refused|*]] | ||
| + | |||
| + | |||
| + | If you are trying to use WinSCP to connect to your iPhone, iPod Touch or iPad, please refer to [[faq_iphone|FAQ]]. | ||
| + | |||
| + | ==== In Other Languages ==== | ||
| + | * //Deutsch// -- Netzwerkfehler: Verbindung zum Host „...“ wurde abgelehnt | ||
| + | * //Español// -- Error de red: conexión a «...» rechazada. | ||
| + | * //Français// -- Erreur réseau : connexion à l'hôte "..." refusée. | ||
| + | * //Italiano// -- Errore di rete: connessione a "..." rifiutata. | ||
| + | |||
| + | ===== [[connection_refused_ftp]] No connection could be made because the target machine actively refused it ===== | ||
| + | The same as [[message_connection_refused|"Network error: Connection refused"]]. | ||
| + | |||
| + | ===== [[connection_timed_out]] Network error: Connection to "..." timed out ===== | ||
| + | All reasons and hints for [[message_connection_refused|"Network error: Connection refused"]] apply to this error too. | ||
| + | |||
| + | ===== [[connection_pemission_denied]] Network error: Permission denied ===== | ||
| + | All reasons and hints for [[message_connection_refused|"Network error: Connection refused"]] apply to this error too. | ||
| + | |||
| + | ===== [[server_rejected_sftp_listens_for_ftp]] The server rejected SFTP connection, but it listens for FTP connections. ===== | ||
| + | Full message is: | ||
| + | |||
| + | > The server rejected SFTP connection, but it listens for FTP connections. | ||
| + | > | ||
| + | > Did you want to use %%FTP%% protocol instead of %%SFTP%%? Prefer using encryption. | ||
| + | |||
| + | The message is always associated with one of the following errors: | ||
| + | |||
| + | * [[message_unexpected_close|Server unexpectedly closed network connection]]; | ||
| + | * [[message_connection_refused|Network error: Connection refused]]; | ||
| + | * [[message_reset_by_peer|Network error: Connection reset by peer]]; | ||
| + | * [[message_connection_timed_out|Network error: Connection timed out]]. | ||
| + | |||
| + | WinSCP uses [[sftp|SFTP protocol by default]], contrary to most other file transfer clients, which use [[ftp|FTP protocol]]. | ||
| + | |||
| + | ~~AD~~ | ||
| + | |||
| + | For this reason, when you try to connect using the default SFTP protocol to a server that does not have SSH/SFTP service (does not have port 22 open), but it has FTP service (port 21 open), it suggests you that you might have actually wanted to use FTP. | ||
| + | |||
| + | You need to select FTP protocol explicitly on [[ui_login|Login dialog]]. | ||
| + | |||
| + | ===== [[no_route_to_host]] Network error: No route to host "..." ===== | ||
| + | All reasons and hints for [[message_connection_refused|"Network error: Connection refused"]] apply to this error too. | ||
| + | It may also be worth trying again later as this error can be due to temporary network issue. | ||
| + | |||
| + | ===== [[timeout_detected]] Timeout detected ===== | ||
| + | If you are getting this error, first try to set longer [[ui_login_connection|timeout interval]]. | ||
| + | |||
| + | If this does not help and you are getting the error while logging in or while initiating file transfer: | ||
| + | |||
| + | * With [[SFTP]] or [[SCP]] protocol, all reasons and hints for [[message_connection_refused|"Network error: Connection refused"]] apply to this error too. | ||
| + | * With [[ftp|FTP protocol]], a reason is likely a firewall/proxy/NAT blocking a data connection. Learn about [[ftp_modes|FTP connection modes and required network configuration]]. | ||
| + | |||
| + | If you are getting the error with the FTP protocol (on a control connection) when finishing a lengthy transfer: | ||
| + | |||
| + | * A reason is typically a broken firewall/proxy/NAT that aborts the %%FTP%% control connection as it sees no traffic during the file transfer. Note that there's no way for WinSCP to keep the control connection alive during the transfer. It would violate the %%FTP%% protocol specification. | ||
| + | |||
| + | ===== [[transfer_channel_cant_be_opened]] Transfer channel can't be opened ===== | ||
| + | |||
| + | A reason is likely a firewall or NAT blocking a data connection. | ||
| + | |||
| + | Learn about [[ftp_modes|FTP connection modes and required network configuration]]. | ||
| + | |||
| + | If the problems happen only intermittently, try setting a longer [[ui_login_connection|server response timeout]]. | ||
| + | |||
| + | ===== [[software_caused_connection_abort]] Network error: Software caused connection abort ===== | ||
| + | |||
| + | ==== While Connecting ==== | ||
| + | You may get this message when connecting to a server for following reasons: | ||
| * Connection was blocked by firewall. Please refer to [[faq_connection_refused|FAQ]]. | * Connection was blocked by firewall. Please refer to [[faq_connection_refused|FAQ]]. | ||
| + | * All reasons and hints for [[message_unexpected_close|"Server unexpectedly closed network connection"]] apply to this error too. | ||
| - | If you are trying to use WinSCP to connect to your iPhone or iPod Touch, please refer to [[faq_iphone|FAQ]]. | + | ==== [[middle]] In a Middle of Session ==== |
| + | If you are getting the error in the middle of session, it means that Windows network code killed an established connection for some reason. For example, it might happen if you pull the network cable out of the back of an Ethernet-connected computer, a DHCP IP address renewal fails or changes the computer's IP address, or if Windows has any other similar reason to believe the entire network has become unreachable.· | ||
| - | ===== Network error: Connection timed out ===== | + | Windows also generates this error if it has given up on the machine at the other end of the connection ever responding to it. If the network between your client and server goes down and your client then tries to send some data, Windows will make several attempts to send the data and will then give up and kill the connection. In particular, this can occur even if you didn't do anything, if you are using SFTP or SCP and WinSCP attempts a [[ui_login_kex#reexchange|key re-exchange]]. |
| - | All reasons and hints for "Network error: Connection refused" above apply to this error too. | + | |
| - | ===== Network error: No route to host ===== | + | The problem can be caused also by the firewall. Try to disable it temporarily to see if the problem persists. Refer to [[faq_connection_refused|FAQ]]. |
| - | All reasons and hints for "Network error: Connection refused" above apply to this error too. | + | |
| - | ===== Host does not exist ===== | + | It can also occur if you are using [[ui_login_connection#keepalives|keepalives]] in your connection. Other people have reported that keepalives fix this error for them. ((&puttydoccite)) |
| + | |||
| + | If you find DHCPNACK errors in the Event Viewer, your DHCP server may be briefly denying your IP address, causing your existing connections to fail. Where possible, this can be addressed by reserving a specific IP address on the DHCP server (e.g. cable modem/router), setting that as the static IP address, and disabling the DHCP client service. | ||
| + | |||
| + | ===== [[host_does_not_exist]] Host "..." does not exist ===== | ||
| You may get this message when connecting to a server for following reasons: | You may get this message when connecting to a server for following reasons: | ||
| * You may have typed a wrong hostname on Login dialog. | * You may have typed a wrong hostname on Login dialog. | ||
| * Your domain name is new and is not fully distributed to DNS servers yet. | * Your domain name is new and is not fully distributed to DNS servers yet. | ||
| * Connection was blocked by firewall. Please refer to [[faq_connection_refused|FAQ]]. | * Connection was blocked by firewall. Please refer to [[faq_connection_refused|FAQ]]. | ||
| + | * Problem with DNS server. | ||
| + | * Common mistake is to enter full URL (e.g. ''%%ftp://ftp.example.com%%'') as hostname on Login dialog instead of actual hostname (e.g. ''%%ftp.example.com%%''). | ||
| + | * In [[scripting]], you may get this error when using ''open site_name'' syntax in an environment, where stored site ''site_name'' does not exist. The ''site_name'' will then be used as a hostname instead. See [[faq_environment|*]] | ||
| + | * Server IPv6 address might by misconfigured. Try forcing IPv4 in //[[ui_login_connection|Internet protocol version]]// session settings. | ||
| - | ===== [[exit_status_1]] Connection has been unexpectedly closed. Server sent command exit status 1 ===== | + | ~~AD~~ |
| - | If you get this error message while logging into your server, it is most usually cause by the server not being able to run some process necessary to support your session. Possibilities are: | + | |
| - | * Shell. Your account may not be allowed to start a shell at all. With some servers (like OpenSSH), you may need to be allowed to start a shell, even if using SFTP protocol. | + | ===== [[network_error_invalid_argument]] Network error: Invalid argument ===== |
| - | * SFTP server. Your account may not be able to start SFTP server binary (e.g. ''/bin/sftp-server'') or the binary is not present on your server. Your SSH server may also lack the SFTP subsystem. | + | |
| + | You may get this message, when your domain policy is set up, not to allow connections from applications located in a certain path, such as a network share. | ||
| + | |||
| + | Typically it helps to install WinSCP to Windows Program Files folder. | ||
| + | |||
| + | ===== [[gethostbyname_unknown_error]] gethostbyname: unknown error ===== | ||
| + | |||
| + | See [[message_network_error_invalid_argument|"Network error: Invalid argument"]]. | ||
| + | |||
| + | ===== [[no_data_of_requested_type_found]] The requested name is valid, but no data of the requested type was found ===== | ||
| + | All reasons and hints for [[message_host_does_not_exist|"Host does not exist"]] apply to this error too. | ||
| + | |||
| + | ===== [[error_code_4]] General failure; Error code: 4 ===== | ||
| + | See [[sftp_codes|SFTP status/error codes]]. | ||
| + | |||
| + | ===== [[unexpected_close]] Server unexpectedly closed network connection ===== | ||
| + | |||
| + | ==== While Connecting ==== | ||
| + | If you get this error message while connecting to your server, it is most usually caused by the server not being able to run some process necessary to support your session. Always try to connect with another SSH (SFTP) client to find, if it is server or client related problem. | ||
| + | |||
| + | Possibilities are: | ||
| + | * Shell. | ||
| + | * Your account may not be allowed to start a shell at all. With some servers (like OpenSSH or Sun SSH), you may need to be allowed to start a shell, even if using SFTP protocol. | ||
| + | * Also some servers refuse to start a shell if your password has expired or your account was terminated. | ||
| + | ····* Some shells do not work with non-interactive sessions. The same is true for some configurations (or profiles used) for otherwise working shells. This commonly exhibits with [[scp|SCP protocol]] with associated error message [[message_startup_message|"Error skipping startup message. Your shell is probably incompatible with the application (BASH is recommended)."]] Try to force ''bash'' shell explicitly on //[[ui_login_scp|SCP/Shell page]]// of Advanced Site Settings dialog. Using [[sftp|SFTP protocol]] instead of SCP is another option. | ||
| + | * OpenSSH server may fail to start shell when chroot is configured, but not possible (e.g. due to group writeable permissions to chroot directory). | ||
| + | * Some environments require specific permissions (e.g. 755) to files like ''.profile'' or ''.bashrc''. | ||
| + | * SFTP server. | ||
| + | * Your account may not be able to start SFTP server binary (e.g. ''/bin/sftp-server'') or the binary is not present on your server. | ||
| + | * Your SSH server may also lack the SFTP subsystem. | ||
| + | * SSH server: | ||
| + | * Your SSH server, particularly OpenSSH, may not be able to access the server key files, due to an incorrect permissions. | ||
| + | |||
| + | ==== In a Middle of Session ==== | ||
| + | If you get this error message in the middle of the session, it is usually caused by a fatal error on the server. The server error may possibly be initiated by an error on the client (WinSCP) side. | ||
| + | |||
| + | In both cases check the log file of your server to see an actual reason, it closed connection for. | ||
| + | |||
| + | If the problem repeats, try turning off //[[ui_login_connection|Optimize connection buffer size]]//. | ||
| + | |||
| + | ===== [[disconnected]] Disconnected from server ===== | ||
| + | |||
| + | This messages indicates that an FTP server unexpectedly closed a connection. | ||
| + | |||
| + | There were reports((See forum topics [[&forum_topic(14577)|FTPS server disconnect during directory listing = sync fail]], [[&forum_topic(14289)|winscp.com scripting disconnect with FTP over TLS]] and [[&forum_topic(11568)|Synchronization: Reconnect and continue during file compare]].)) that the disconnect is sometimes caused by a Windows firewall on a local machine or on a remote server (if the server runs on Windows), if a stateful %%FTP%% filtering is enabled on the firewall. | ||
| + | |||
| + | To disable the stateful %%FTP%% filtering, in an Administrator command prompt, execute following command: | ||
| + | |||
| + | <code batch> | ||
| + | netsh advfirewall <nohilite>set</nohilite> global StatefulFTP disable | ||
| + | </code> | ||
| + | |||
| + | For details refer to [[https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/dd421710(v=ws.10)|How to Configure Windows Firewall for a Passive Mode FTP Server]]. | ||
| + | |||
| + | ===== Incoming packet was garbled on decryption ===== | ||
| + | This error occurs when WinSCP decrypts an SSH packet and the decrypted data makes no sense. This probably means something has gone wrong in the encryption or decryption process. It's difficult to tell from this error message whether the problem is in the client or in the server, or in between. | ||
| + | |||
| + | You can try enabling //[[ui_login_bugs#sshbug_derivekey2|Miscomputes SSH encryption keys]]// or //[[ui_login_bugs#sshbug_maxpkt2|Ignores SSH maximum packet size]]// session option. | ||
| + | |||
| + | Sometimes the error is a result of the connection fatally failing for whatever reason even completely unrelated to the encryption. For example, when the server runs out of disk space. | ||
| + | |||
| + | ===== [[exit_status_1]] Connection has been unexpectedly closed. Server sent command exit status 1 (or 0 or 127 or 255) ===== | ||
| + | All reasons and hints for [[message_unexpected_close|"Server unexpectedly closed network connection"]] apply to this error too. | ||
| + | |||
| + | ===== [[reset_by_peer]] Network error: Connection reset by peer ===== | ||
| + | All reasons and hints for [[message_unexpected_close|"Server unexpectedly closed network connection"]] apply to this error too. | ||
| + | |||
| + | ===== [[host_is_not_communicating]] Host is not communicating for more than 15 seconds. Still waiting... Warning: Aborting this operation will close connection! ===== | ||
| + | You get this message when WinSCP is waiting for response from the server for more than [[ui_login_connection#timeout|configured time]]. Note that this is not an error message, WinSCP still keeps waiting. If the server responds finally, the message goes away automatically. The message box is shown only to give you a chance to break the connection and reconnect, if you do not want to wait anymore. | ||
| + | |||
| + | If the server never replies, it may be because of some fatal error on the server side. Also something may be interfering with the connection, preventing the server response from arriving or possibly even the original request to arrive at the server. | ||
| + | |||
| + | ==== [[persistent]] Persistent problems ==== | ||
| + | |||
| + | If the problem repeats, try turning off //[[ui_login_connection|Optimize connection buffer size]]//. | ||
| + | |||
| + | In [[scripting]], you can turn off the buffer optimization using [[rawsettings#sendbuf|''SendBuf'' raw session settings]]: | ||
| + | <code winscp> | ||
| + | open sftp://user:password@example.com/ -rawsettings SendBuf=0 | ||
| + | </code> | ||
| + | |||
| + | Similarly in [[library|WinSCP .NET assembly]] (a [[library_powershell|PowerShell]] example): | ||
| + | <code powershell> | ||
| + | $sessionOptions = New-Object WinSCP.SessionOptions | ||
| + | ... | ||
| + | $sessionOptions.AddRawSettings("SendBuf", "0") | ||
| + | </code> | ||
| + | |||
| + | Some users also experience this message, when they run out of disk space/quota on the server. | ||
| + | |||
| + | ==== In Other Languages ==== | ||
| + | * //Deutsch// -- Der entfernte Rechner kommuniziert seit mehr als 15 Sekunden nicht mehr. Warte... Warnung: Der Abbruch dieser Operation beendet die Verbindung! | ||
| + | * //Español// -- El servidor no se ha comunicado por mas de 15 segundos. Sigo esperando... Aviso: si abortas la operación la sesión se cerrará! | ||
| + | * //Français// -- L'hôte n'a pas répondu pendant plus de 15 secondes. Toujours en attente... Attention : Annuler cette opération va fermer la connexion ! | ||
| + | * //Italiano// -- L'host non sta comunicando per più di 15 secondi. In attesa... Avviso: Interrompendo questa operazione chiuderai la connessione! | ||
| + | |||
| + | ~~NOTOC~~ | ||
| + | |||
| + | ===== [[access_denied]] Access denied ===== | ||
| + | You will get the error while authenticating when: | ||
| + | * You have entered incorrect password, used non-authorized key, etc. | ||
| + | * The account you are trying to use cannot be logged in. This can be case even when you get //"Access denied"// only after entering password, as for security reasons, many servers do not reveal information about the accounts. Reasons for not being allowed to login include: | ||
| + | * The account (username) you have entered on Login dialog does not exist at all. | ||
| + | * The account is disabled. | ||
| + | * The password has expired. | ||
| + | * Number of parallel sessions allowed for the account has been exceeded. | ||
| + | * You are trying to connect with super-user account (''root''), without having allowed that. Please read [[faq_su|FAQ]]. | ||
| + | It may help to check log file of your server to see an actual reason, it denied you an access. | ||
| + | |||
| + | If you are not controlling the server, seek help with your server administrator (e.g. your webhosting provider). | ||
| + | |||
| + | See also [[faq_username|*]] | ||
| + | |||
| + | ===== [[key_refused]] Server refused our key ===== | ||
| + | If you see this message, it means that WinSCP has sent a public key to the server and offered to authenticate with it, and the server has refused to accept authentication. This usually means that the server is not configured to accept this key to authenticate this user. | ||
| + | |||
| + | This is almost certainly not a problem with WinSCP. If you see this type of message, the first thing you should do is check your server configuration carefully. Common errors include having the wrong permissions or ownership set on the public key or the user's home directory on the server. Also, read the WinSCP [[logging|session log]]; the server may have sent diagnostic messages explaining exactly what problem it had with your setup. ((&puttydoccite)) | ||
| + | |||
| + | Learn how to [[guide_public_key|*]]. | ||
| + | |||
| + | ===== [[permission_denied]] Permission denied ===== | ||
| + | You do not have sufficient permissions (access rights) to a resource, such as a file or directory, to perform the operation. | ||
| + | |||
| + | You should contact the server administrator to resolve the problem. | ||
| + | |||
| + | Access rights systems differ with operating system and the file server. With the most common combination of Unix-based system and OpenSSH: | ||
| + | * To see a directory contents you need to have read permissions to the directory; | ||
| + | * To read a file you need to have read permissions to the file; | ||
| + | * To write a file you need to have a write permissions to the file; | ||
| + | * To create or delete file you need have a write permissions to the directory; | ||
| + | * To change file or directory permissions you need to be its owner; | ||
| + | * To change file modification time you need to be its owner (note that by default WinSCP [[ui_transfer_custom#common|updates file modification time]] when uploading). | ||
| + | |||
| + | ===== [[too_many_authentication_failures]] Server sent disconnect message type 2 (protocol error): "Too many authentication failures for root" ===== | ||
| + | This message is produced by an OpenSSH (or Sun SSH) server if it receives more failed authentication attempts than it is willing to tolerate. | ||
| + | |||
| + | This can easily happen if you are using [[ui_pageant|Pageant]] and have a large number of keys loaded into it, since these servers count each offer of a public key as an authentication attempt. This can be worked around by specifying the key that's required for the authentication in the [[ui_login#session_settings]]; WinSCP will ignore any other keys Pageant may have, but will ask Pageant to do the authentication, so that you don't have to type your passphrase. ((&puttydoccite)) | ||
| + | |||
| + | ===== [[key_is_of_wrong_type]] Unable to use this private key file, Couldn't load private key, Key is of wrong type ===== | ||
| + | If you see one of these messages, it often indicates that you've tried to load a key of an inappropriate type into WinSCP. | ||
| + | |||
| + | You may have specified a key that's inappropriate for the connection you're making. The SSH-1 and SSH-2 protocols require different private key formats, and a SSH-1 key can't be used for a SSH-2 connection. | ||
| + | |||
| + | Alternatively, you may have tried to load a key in a "foreign" format (OpenSSH or ssh.com), in which case you need to [[public_key#private|import it into PuTTY's native format]]. ((&puttydoccite)) | ||
| + | |||
| + | ===== [[unexpected_directory_listing]] Unexpected directory listing line '...' ===== | ||
| + | You will get the error with [[scp|SCP protocol]], if output of ''ls'' command cannot be parsed by WinSCP. WinSCP expects listing in format: | ||
| + | <type><permissions> <inode> <owner> <group> <size> <timestamp> <filename>[ -> <target>] | ||
| + | |||
| + | ~~AD~~ | ||
| + | |||
| + | Some common examples: | ||
| + | |||
| + | drw-r--r-- 3 martinp users 4596 2007-06-06 11:18:33.000000000 +0200 private | ||
| + | |||
| + | lrwxrwxrwx 1 martinp users 4 Mar 24 2005 wiki -> dokuwiki | ||
| + | |||
| + | drwxr-xr-x+ 2 martinp users 96 Oct 26 14:58 httpdocs | ||
| + | |||
| + | If your listing does not correspond to some of the above: | ||
| + | * Try using [[sftp|SFTP protocol]] instead of SCP. | ||
| + | * Always make sure you are using the latest version of WinSCP, as support for different listing format is being added continuously. | ||
| + | * Alter output of ''ls'' command to match any of the supported formatting. WinSCP has few session options that may be used for that, including: | ||
| + | * //[[ui_login_scp#directory_listing|Listing command]]// (e.g. use ''sed'' to modify output of ''ls'' command to match the WinSCP requirements); | ||
| + | * //[[ui_login_scp#other_options|Clear aliases]]// (may help if the ''ls'' command is aliased to display non standard output) and | ||
| + | * //[[ui_login_scp#other_options|Clear national variables]]// (may help if your listing does not use English month names). | ||
| + | * Make sure you are using ''bash'' shell. If you do not want to set it as your default shell, [[ui_login_scp#shell|force it]] for WinSCP sessions. | ||
| ===== [[large_packet]] Received too large (... B) SFTP packet. Max supported packet size is 102400 B ===== | ===== [[large_packet]] Received too large (... B) SFTP packet. Max supported packet size is 102400 B ===== | ||
| - | If ... (from the subject) is a very large number then the problem is typically caused by a message printed from some profile/logon script. It violates the SFTP protocol. Some of these scripts are executed even for [[requirements#configuring_winscp_sessions|non-interactive (no TTY) sessions]], so they cannot print anything (nor ask user to type something). | + | If ... (from the subject) is a very large number then the problem is typically caused by a message printed from some profile/logon script. It violates an SFTP protocol. Some of these scripts are executed even for [[requirements#remote_environment|non-interactive (no TTY) sessions]], so they cannot print anything (nor ask user to type something). |
| - | The number ... represents the first four bytes read from the server. If your login scripts are printing words, this will be the first four characters cast into a number, and not an SFTP message at all. | + | The number ... represents the first four bytes read from the server. If your login scripts are printing words, these will be the first four characters cast into a number, and not an %%SFTP%% message at all. |
| - | To fix the problem find out what command in your login script prints text. Once you find it move the command to the proper interactive script, or remove it entirely. The scripts are usually hidden (their name starts with dot) and are located in your home directory on the server. | + | To fix the problem, find out, what command in your login script prints the text. Once you find it, move the command to a proper interactive script, or remove it entirely. The scripts are usually hidden (their name starts with dot) and are located in your home directory on the server. Typically you will need to move the commands from ''.bashrc'' script to ''.bash_profile''. |
| - | There are other possible sources of the message in addition to the profile script - some SSH servers print messages if they are unable to start the SFTP server, or encounter a fatal error. You should contact your server administrator. | + | There are other possible sources of the message in addition to the profile script -- some SSH servers print messages, if they are unable to start an %%SFTP%% server, or encounter a fatal error. You should contact your server administrator. |
| - | Another possibility is that the server is configured to only allow the SCP protocol and not the SFTP protocol, in such a way that SCP fallback mechnism of WinSCP does not work. The solution is to choose SCP protocol on the [[ui_login_session|login dialog]]. | + | Another possibility is that the server is configured to only allow an SCP protocol and not the %%SFTP%% protocol, in such a way that %%SCP%% fallback mechanism of WinSCP does not work. The solution is to explicitly choose %%SCP%% protocol on the [[ui_login#session_settings|Login dialog]]. |
| - | ===== Invalid access to memory ===== | + | ===== [[return_code_127]] Command failed with return code 127 (or 255) ===== |
| + | You will get the error with [[scp|SCP protocol]], if command necessary for facilitate operation you were trying to do does not exist on remote server or the shell cannot find it. | ||
| + | If you are not an experienced Unix user, you should first try using [[sftp|SFTP protocol]] instead. | ||
| + | |||
| + | If you are sure that the command exists on the remote server, make sure that WinSCP (or rather the shell) can find it. You may need to add path to the command to ''PATH'' environment variable. Also make sure that the startup script that sets ''PATH'' is actually executed for non-interactive sessions. | ||
| + | |||
| + | You can also try to run the respective command from terminal (with the same account that you use with WinSCP), to verify that you can execute it. You may not have sufficient permissions, or the command dependencies may not be installed. | ||
| + | |||
| + | Common situations, in which you may get the error: | ||
| + | * Transferring files fails, because path to ''scp'' command is not in ''PATH''; | ||
| + | * Error appears while logging in, because your *nix distribution lacks ''groups'' command. You can instruct WinSCP not to use the command in [[ui_login_scp#other_options|site settings]]. | ||
| + | |||
| + | ===== [[not_able_to_determine_application_started]] WinSCP was not able to determine application that was started to open the file. WinSCP cannot watch for changes in the file and thus it will not upload the changed file back ===== | ||
| + | |||
| + | See [[task_edit#mdi|documentation]]. | ||
| + | |||
| + | ===== [[startup_message]] Error skipping startup message. Your shell is probably incompatible with the application (BASH is recommended) ===== | ||
| + | This error is typically associated with another error. If there is no other error in the message, try searching a [[logging|session log file]]. | ||
| + | |||
| + | ===== [[empty_listing_for_directory]] Server returned empty listing for directory ===== | ||
| + | Check that you have read and execute permissions to the directory. | ||
| + | |||
| + | ===== [[timeout_external_console]] Timeout waiting for external console to complete the command ===== | ||
| + | This error indicates that ''[[executables|winscp.exe]]'' did not receive an answer from ''[[executables|winscp.com]]'' in time. | ||
| + | |||
| + | Most commonly this happens when ''winscp.com'' has redirected output to a stream with limited buffer. If the stream is not being read from, the buffer gets eventually filled and ''winscp.com'' hangs, when trying to write into it. | ||
| + | |||
| + | In turn the above most commonly happens when ''winscp.com'' is run from another program (such as .NET code), which redirect its output into stream. If the program then e.g. waits for ''winscp.com'' to finish without reading from the stream, the ''winscp.com'' eventually hangs, never finishing. | ||
| + | |||
| + | See example of [[guide_dotnet|.NET]] or [[guide_automation_advanced#inout|WSH]] code dealing with the problem. | ||
| + | |||
| + | When using [[library|WinSCP .NET assembly]], this problem should not happen, as the assembly already takes care of continuous reading of the output. | ||
| + | |||
| + | ===== [[error_listing_directory]] Error listing directory ===== | ||
| + | This is high-level error, and it is typically associated with another error, such as: | ||
| + | * [[message_timeout_detected|Timeout detected]]; | ||
| + | * [[message_unexpected_directory_listing|Unexpected directory listing line '...']]. | ||
| + | |||
| + | ~~AD~~ | ||
| + | |||
| + | ===== [[cannot_initialize_sftp_protocol]] Cannot initialize SFTP protocol. Is the host running a SFTP server? ===== | ||
| + | The error is frequently associated (and caused by) with following errors: | ||
| + | * [[message_unexpected_close|"Server unexpectedly closed network connection"]]; | ||
| + | * [[message_exit_status_1|"Connection has been unexpectedly closed. Server sent command exit status 1 (or 255 or 0)"]]; | ||
| + | * [[message_large_packet|"Error Received too large (... B) SFTP packet. Max supported packet size is 102400 B"]]. | ||
| + | |||
| + | The error can also indicate interoperability problems with the SFTP server. Try decreasing //[[ui_login_sftp|Preferred SFTP protocol version]]// to //3//, which usually have more stable implementation on the servers. | ||
| + | |||
| + | ~~AD~~ | ||
| + | |||
| + | ===== [[cannot_open_active_connection]] The server cannot open connection in active mode. If you are behind a NAT router, you may need to specify an external IP address. Alternatively, consider switching to passive mode. ===== | ||
| + | The error happens, when the server does not open connection to WinSCP to perform file or directory listing transfer. | ||
| + | |||
| + | To resolve the problem try: | ||
| + | * Specifying your [[ui_pref_network|external IP address]]; | ||
| + | * Switching to the [[ui_login_connection|passive mode]]. | ||
| + | |||
| + | Read more about [[ftp_modes|FTP connection modes]]. | ||
| + | |||
| + | ===== [[name_no_data]] The requested name is valid and was found in the database, but it does not have the correct associated data being resolved for ===== | ||
| + | The usual example for this is a host name-to-address translation attempt which uses the DNS (Domain Name Server). An MX record is returned but no A record—indicating the host itself exists, but is not directly reachable. | ||
| + | |||
| + | This can possibly happen for newly registered domain names that are no fully setup yet. | ||
| + | |||
| + | ===== [[transfer_finished_could_not_rename]] Transfer was successfully finished, but temporary transfer file ... could not be renamed to target file name ... ===== | ||
| + | With SFTP protocol, when [[resume#automatic|automatic transfer resume]] is enabled, WinSCP first uploads the file to a temporary file with ''.filepart'' extension. Only after the transfer is completed the file is renamed to its actual name. | ||
| + | |||
| + | For you the renaming failed, for which there are many possible reasons including: | ||
| + | * Your SFTP server does not support renaming files; | ||
| + | * There's some process that takes the uploaded file away immediately, before WinSCP is able to rename it. | ||
| + | * There's antivirus (or similar application) that starts inspecting the uploaded file, locking it while doing that, what conflicts with WinSCP attempt to rename the file. | ||
| + | |||
| + | To circumvent that, disable transfer resume/transfer to temporary filename. | ||
| + | |||
| + | * In GUI, go to [[ui_pref_resume|//Preferences > Transfer > Endurance//]] and disable [[ui_pref_resume#temporary|//Transfer Resume / Transfer to Temporary Filename//]]. | ||
| + | * In scripting, use [[scriptcommand_put#resumesupport|''-resumesupport=off'' with ''put'' command]] (or other command that triggered the upload). | ||
| + | * In .NET assembly, use ''[[library_transferoptions#resumesupport|TransferOptions.ResumeSupport]]'' property. | ||
| + | |||
| + | ===== [[preserve_time_perm]] Upload of file .. was successful, but error occurred while setting the permissions and/or timestamp. If the problem persists, turn off setting permissions or preserving timestamp. Alternatively you can turn on 'Ignore permission errors' option. ===== | ||
| + | You get this error, when a server fails to update file timestamp or permissions for some reason: | ||
| + | * On some systems (e.g. Linux), you need to be an owner of the file (write permissions are not enough) to modify its permissions or timestamp (you will see an error like //"Permissions denied"// in error details). | ||
| + | * Some servers do not support updating file timestamp or permissions at all (you will see an error like //"The server does not support the operation"// in error details). | ||
| + | * Some servers are set up to pickup any uploaded file immediately, process it somehow and delete or move it away. If the server is quick enough, it does that before WinSCP is able to update the file timestamp or permissions (you will see an error like //"No such file or directory"// in error details). | ||
| + | |||
| + | Whatever the reason is, you need to turn off //[[ui_transfer_custom#upload|Set permissions]]// and //[[ui_transfer_custom#common|Preserve timestamp]]// options or turn on //[[ui_transfer_custom#upload|Ignore permission errors]]//. | ||
| + | |||
| + | Note that you cannot disable preserving timestamp for [[task_synchronize|synchronization]], unless you turn off //Modification timestamp// [[ui_synchronize#criteria|comparison criteria]]. | ||
| + | |||
| + | ==== [[scripting]] Scripting ==== | ||
| + | |||
| + | When using [[scripting]], add [[scriptcommand_put#nopreservetime|''-nopreservetime'' switch]] to [[scriptcommand_put|''put'' command]]. If you are not running scripting with [[scripting#configuration|default isolated configuration]], you may also need to add [[scriptcommand_put#nopermissions|''-nopermissions'' switch]] (what is the default settings). | ||
| + | |||
| + | With [[scriptcommand_synchronize|''synchronize'' command]], this works only when ''[[scriptcommand_synchronize#criteria|-criteria]]'' lacks ''time'' and it never works in ''both'' mode. | ||
| + | |||
| + | ==== [[library]] .NET Assembly ==== | ||
| + | |||
| + | When using [[library|.NET assembly]], set ''[[library_transferoptions|TransferOptions]]'' as shown in following examples: | ||
| + | |||
| + | C# example: | ||
| + | |||
| + | <code csharp> | ||
| + | TransferOptions transferOptions = new TransferOptions(); | ||
| + | ... | ||
| + | transferOptions.FilePermissions = null; // This is default | ||
| + | transferOptions.PreserveTimestamp = false; | ||
| + | </code> | ||
| + | |||
| + | PowerShell example: | ||
| + | |||
| + | <code powershell> | ||
| + | $transferOptions = New-Object WinSCP.TransferOptions | ||
| + | ... | ||
| + | $transferOptions.FilePermissions = $Null # This is default | ||
| + | $transferOptions.PreserveTimestamp = $False | ||
| + | </code> | ||
| + | |||
| + | With [[library_session_synchronizedirectories|''Session.SynchronizeDirectories'']], this works only when ''criteria'' parameter lacks ''SynchronizationCriteria.Time'' and it never works when ''mode'' parameter is ''SynchronizationMode.Both'' (learn [[library_powershell#enums|enumeration syntax]] in PowerShell). | ||
| + | |||
| + | ==== In Other Languages ==== | ||
| + | * //Deutsch// -- Das Hochladen der Datei ... war erfolgreich, aber es trat ein Fehler beim Setzen der Berechtigungen und/oder der Dateizeit auf. Wenn das Problem weiterbestehen bleibt, schalten Sie die Option 'Berechtigungsfehler ignorieren' ein. | ||
| + | * //Español// -- Subida de archivo ... fue exitosa, pero ocurrió un error mientras se asignavan los permisos o la fecha. Si el problema persiste, apage la opción de permisos o conservar fecha. Opcionalmente puedes intentar con la opción de'Ignorar Errores de permisos'. | ||
| + | * //Français// -- Envoi du fichier ... réussi, mais une erreur est survenue lors de l'ajout des permissions et/ou de l'horodatage. Si le problème persiste, désactiver l'ajout des permissions ou la préservation de l'horodatage. Autrement, vous pouvez activer l'option 'Ignorer les erreurs de permission' | ||
| + | * //Italiano// -- Upload del file ... terminato con successo, ma si è verificato un errore impostando permessi e/o timestamp. Se il problema persiste, disattiva 'Imposta permessi' o 'Mantieni timestamp'. In alternativa puoi attivare 'Ignora errori su permessi'. | ||
| + | |||
| + | ~~NOTOC~~ | ||
| + | |||
| + | ===== [[supplied_message_incomplete]] The supplied message is incomplete. The signature was not verified. ===== | ||
| + | |||
| + | This error is returned by Windows IIS server due to a known bug. | ||
| + | |||
| + | For details see a Microsoft article [[https://support.microsoft.com/en-us/topic/fix-the-supplied-message-is-incomplete-error-when-you-use-an-ftps-client-to-upload-a-file-in-windows-0da7e32a-509f-c2d5-7a44-2d1d34ef817a|FIX: "The supplied message is incomplete" error when you use an FTPS client to upload a file in Windows]]. | ||
| + | |||
| + | ===== [[library_process_terminated_with_exit_code_3]] WinSCP process terminated with exit code 3 ===== | ||
| + | |||
| + | The full error message usually also contains //"There was no output. Response log file "..." was not created. This could indicate lack of write permissions to the log folder or problems starting WinSCP itself."// | ||
| + | |||
| + | This error indicates that WinSCP process started by WinSCP .NET assembly did not correctly start. Make sure your process has permissions to access WinSCP [[executables|executable]] and to execute processes. See also [[bug>996|related fix for for frequent use of the .NET assembly]]. | ||
| + | |||
| + | ===== [[library_timeout_waiting_to_respond]] Timeout waiting for WinSCP to respond ===== | ||
| + | |||
| + | This error comes in variants: | ||
| + | * //Timeout waiting for WinSCP to respond -- WinSCP has not responded in time// | ||
| + | * //Timeout waiting for WinSCP to respond -- Log file ... was not created in time, please make sure WinSCP has write permissions to the folder// | ||
| + | |||
| + | ~~AD~~ | ||
| + | |||
| + | There are several possible reasons for the error: | ||
| + | * WinSCP was run using a different local account and cannot communicate with the [[library|.NET assembly]]. This typically happens, when the assembly is used in IIS web application and impersonation is turned on. Turn the impersonation off for the web application that uses the assembly. Alternatively, if you know, what account is being used, use the ''[[library_session#executableprocessusername|Session.ExecutableProcessUserName]]'' and the ''[[library_session#executableprocesspassword|Session.ExecutableProcessPassword]]'' to configure the local account to use for the WinSCP process. | ||
| + | * WinSCP could not create/write to log file that it uses to report back to the .NET assembly. Make sure your process has write permissions to the temporary folder. Alternatively, you can use (undocumented) property ''Session.XmlLogPath'' to change the log file location. | ||
| + | * WinSCP did not correctly start. Make sure your process has permissions to access WinSCP [[executables|executable]] and to execute processes. See also [[bug>996|related fix for frequent use of the .NET assembly]]. | ||
| + | * If the problem happend intermittently, try setting longer [[library_session#timeout|''Session.Timeout'']]. The machine running your code or the server might be overloaded temporarily. | ||
| + | * One some locales (e.g. Welsh), old versions of WinSCP had problems recognizing command-line arguments from the .NET assembly. See [[bug>1436|related fix]]. | ||
| + | |||
| + | ===== [[cannot_initialize_external_console]] Cannot initialize external console ===== | ||
| + | |||
| + | If you are getting the error with [[library|WinSCP .NET assembly]] and the error details are like //"Request event -- System Error. Code: 5. -- Access is denied"//, the error indicates that the .NET assembly cannot communicate with [[executables|WinSCP executable]]. This usually happens, when the .NET assembly is used within a restricted environment like IIS Web Service as the assembly and the process are using different local accounts. | ||
| + | |||
| + | Use the ''[[library_session#executableprocessusername|Session.ExecutableProcessUserName]]'' and the ''[[library_session#executableprocesspassword|Session.ExecutableProcessPassword]]'' to configure the local account to use for the WinSCP process. | ||
| + | |||
| + | Though in general, WinSCP .NET assembly is [[library#purpose|not the right tool to be used for web development]]. | ||
| + | |||
| + | ===== [[net_operation_not_supported]] Could not load file or assembly 'file:///...\WinSCPnet.dll' or one of its dependencies. Operation is not supported. (Exception from HRESULT: 0x80131515) ===== | ||
| + | You may get this error, if the [[library_install|WinSCP .NET assembly package]] was downloaded using Microsoft Internet Explorer or Edge browsers and extracted using Windows File Explorer. These applications, under certain circumstances, block libraries downloaded from Internet as potentially harmful, what prevents their loading. | ||
| + | |||
| + | To remove the block, open //Properties// for the ''WinSCPnet.dll'' in Windows File Explorer. On an initial //General// page, click //Unblock// button on //Security// section. Alternatively, you can use ''[[ps>microsoft.powershell.utility/unblock-file|Unblock-File]]'' PowerShell cmdlet. | ||
| + | |||
| + | You may need to restart your IDE (if any), for the change to apply. | ||
| + | |||
| + | ===== [[net_system_cannot_find_file_specified]] Could not load file or assembly 'file:///...\WinSCPnet.dll' or one of its dependencies. The system cannot find the file specified. ===== | ||
| + | You may get this error when using [[library|WinSCP .NET assembly]] from restricted environments, such as [[library_ssis|SSIS]]. To use the assembly from SSIS, it needs to be [[library_install#gac|installed to GAC]]. Also make sure you have installed the same version that you reference in your SSIS package. Alternatively, you can [[library_ssis#subscribe|subscribe ''AppDomain.AssemblyResolve'' event]] to allow loading the assembly. | ||
| + | |||
| + | If the above is not your case, use [[https://learn.microsoft.com/en-us/dotnet/framework/tools/fuslogvw-exe-assembly-binding-log-viewer|Assembly Binding Log Viewer]] (''Fuslogvw.exe'') to debug assembly loading. | ||
| + | |||
| + | ===== [[net_runtime_newer_than_currently_loaded]] Could not load file or assembly 'file:///...\WinSCPnet.dll' or one of its dependencies. This assembly is built by a runtime newer than the currently loaded runtime and cannot be loaded. ===== | ||
| + | The latest version of [[library|WinSCP .NET assembly]] targets .NET Framework 4.0 and .NET Standard 2.0. | ||
| + | |||
| + | You are attempting to load the assembly with an older version of .NET. | ||
| + | |||
| + | You can get this error even if your system has the required version of .NET installed, if you are loading the assembly in an environment that has (an older version of) .NET loaded already. This typically happens with older versions of PowerShell. To fix this, either upgrade your PowerShell version, or have your old PowerShell version load newer version of .NET. You can use ''COMPLUS_version'' environment variable for that: | ||
| + | |||
| + | <code batch> | ||
| + | set COMPLUS_version=v4.0.30319 | ||
| + | powershell | ||
| + | </code> | ||
| + | |||
| + | For details and other options, see [[https://stackoverflow.com/q/2094694/850848|How can I run PowerShell with the .NET 4 runtime?]] | ||
| + | |||
| + | ===== [[net_exception_thrown_target_invocation]] Exception has been thrown by the target of an invocation ===== | ||
| + | |||
| + | This is just a high-level exception. The root cause is usually stored in the ''[[dotnet>system.exception.innerexception|InnerException]]''. | ||
| + | |||
| + | If you are getting this exception in SSIS, you can use ''try'' ... ''catch'' block to capture the error, as show in the [[library_ssis#example|example for using WinSCP .NET Assembly from SSIS]]. Though this won't help if the error occurs even before the SSIS ''Main'' method is started. In this case, the actual error should be shown on the //Progress// tab of your SSIS package. Often, the root cause can be loading of ''WinSCPnet.dll'' assembly. See [[message_net_system_cannot_find_file_specified|Could not load file or assembly ‘file:///…\WinSCPnet.dll’ or one of its dependencies. The system cannot find the file specified]]. | ||
| + | |||
| + | If you do not use SSIS and you cannot access the inner exception easily, inspect WinSCP session log and debug log file (''[[library_session#sessionlogpath|Session.SessionLogPath]]'', ''[[library_session#debuglogpath|Session.DebugLogPath]]''). | ||
| + | |||
| + | ===== [[sessionoptions_sshhostkeyfingerprint_is_not_set]] SessionOptions.Protocol is Protocol.Sftp or Protocol.Scp, but SessionOptions.SshHostKeyFingerprint is not set ===== | ||
| + | |||
| + | When connecting using SFTP or SCP protocols, which run over [[ssh|SSH]], [[ssh_verifying_the_host_key|server's host key must be verified]]. In [[library|WinSCP .NET assembly]], you do by setting [[library_sessionoptions#sshhostkeyfingerprint|''SessionOptions.SshHostKeyFingerprint'' property]] to the value of fingerprint of the expected host key. | ||
| + | |||
| + | A C# example: | ||
| + | |||
| + | <code csharp> | ||
| + | SessionOptions sessionOptions = new SessionOptions | ||
| + | { | ||
| + | Protocol = Protocol.Sftp, | ||
| + | HostName = "example.com", | ||
| + | UserName = "username", | ||
| + | Password = "password", | ||
| + | SshHostKeyFingerprint = "ssh-rsa 2048 2EPqmpSRaRtUIqwvm15rzavssrhHxJ3avJWh9mBaz8M=", | ||
| + | }; | ||
| + | </code> | ||
| + | |||
| + | To learn how to find the value of the fingerprint see [[faq_hostkey|*]] | ||
| + | |||
| + | Though as with the most of session settings, if you have the site set up in WinSCP GUI, you can have it [[ui_generateurl#code|generate a code template]] for you, including the ''SessionOptions.SshHostKeyFingerprint''. | ||
| + | |||
| + | ===== [[method_not_found_eventwaithandle]] Method not found: 'Void System.Threading.EventWaitHandle..ctor(...)' ===== | ||
| + | |||
| + | Full message: | ||
| + | |||
| + | > Method not found: ‘Void System.Threading.EventWaitHandle..ctor(Boolean, System.Threading.EventResetMode, System.String, Boolean ByRef, System.Security.AccessControl.EventWaitHandleSecurity)’ | ||
| + | |||
| + | The exception can be represented as ''MethodInvocationException'' or ''MissingMethodException''. | ||
| + | |||
| + | The exception occurs, when you are trying to use .NET Framework build of the assembly in .NET [Core] code or from PowerShell [Core]. | ||
| + | |||
| + | You need to use .NET Standard build of the assembly, which is located in the ''netstandard2.0'' subfolder of ''WinSCP-X.X.X-Automation.zip'' package. | ||
| + | |||
| + | For details, learn about [[library_install#installing|installing the assembly]]. | ||
| + | |||
| + | ===== [[key_fingerprint_does_not_match]] SSH host key/TLS host certificate fingerprint "..." does not match pattern "..." ===== | ||
| + | |||
| + | You get these errors, when the SSH host key fingerprint provided to [[library_sessionoptions#sshhostkeyfingerprint|''SessionOptions.SshHostKeyFingerprint'']] or TLS host certificate fingerprint provided to [[library_sessionoptions#tlshostcertificatefingerprint|''SessionOptions.TlsHostCertificateFingerprint'']] have a wrong format. | ||
| + | |||
| + | (In [[library_powershell|PowerShell]], when setting the properties via ''-Property'' switch of [[https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-object|''New-Object'' cmdlet]], the error is disguised by PowerShell as //"The value supplied is not valid, or the property is read-only. Change the value, and then try again."//) | ||
| + | |||
| + | Examples of the correct format of the fingerprints: | ||
| + | |||
| + | * Base64-encoded SHA-256 SSH host key fingerprint: \\ ''ssh-rsa 2048 2EPqmpSRaRtUIqwvm15rzavssrhHxJ3avJWh9mBaz8M='' | ||
| + | * Hex-encoded %%SHA-256%% TLS host certificate fingerprint: \\ ''b0:ea:9e:a2:0b:90:58:72:4c:dc:bc:5d:83:0e:bf:02:ef:28:9d:b8:8e:26:bc:25:bd:36:4b:17:50:1b:c8:da'' | ||
| + | |||
| + | Easiest way to get the fingerprints in the correct format is to have [[ui_generateurl|WinSCP generate a code template]] in your preferred language for you. For other options, see also [[faq_hostkey|*]] | ||
| + | |||
| + | Also make sure you use the same version (ideally the latest) of WinSCP both for obtaining the fingerprint in WinSCP GUI and using the fingerprint in WinSCP .NET assembly. Older versions do not support modern SHA-256 fingerprints. So the fingerprint formats may be incompatible (and less safe). | ||
| + | |||
| + | A common mistake is to substitute ''SessionOptions.TlsHostCertificateFingerprint'' with ''SessionOptions.SshHostKeyFingerprint'' (or vice versa). The SSH host key is used with SSH-based protocols SFTP and FTP. The TLS host certificate is used with SSL-based protocols FTPS, WebDAVS and S3. | ||
| + | |||
| + | ===== [[path_slash_ambiguous]] Selecting files using a path ending with slash is ambiguous. Remove the slash to select the folder. Append * mask to select all files in the folder. ===== | ||
| + | |||
| + | When selecting files for an operation, you have specified a source path like ''/remote/'' (or ''C:\local\''). | ||
| + | |||
| + | For example: | ||
| + | |||
| + | <code winscp> | ||
| + | get /remote/ C:\local\ | ||
| + | </code> | ||
| + | |||
| + | The recommended syntax is either ''/remote/*'' (''C:\local\*'') or ''/remote'' (''C:\local''). | ||
| + | |||
| + | The syntax with ''*'' [[file_mask|file mask]] (wildcard) will select files in the directory for the operation. | ||
| + | |||
| + | For example the following code will download all files from the ''/remote'' directory to the ''C:\local'' directory: | ||
| + | |||
| + | <code winscp> | ||
| + | get /remote/* C:\local\ | ||
| + | </code> | ||
| + | |||
| + | Contrary, the syntax without the file mask (wildcard) and an ending slash (backslash) will select the directory itself for the operation. | ||
| + | |||
| + | For example the following code will download the ''/remote'' directory to ''C:\local'' directory. It means, the ''remote'' will be created as subdirectory of the ''C:\local'' directory. The files from ''/remote'' will be downloaded to the ''C:\local\remote''. | ||
| + | |||
| + | <code winscp> | ||
| + | get /remote C:\local\ | ||
| + | </code> | ||
| + | |||
| + | The syntax with the ending slash is considered ambiguous. It's not clear if you wanted to select the directory itself or the files in the directory. WinSCP will behave unpredictably, when you use this syntax. The behavior might change with protocol and path syntax. The behavior may also change in future releases of WinSCP or the format can be banned altogether. Use one the two formats described above, depending on your needs. | ||
| + | |||
| + | ===== [[special_code]] Sending special code: 12/15 ===== | ||
| + | This is not an error message, nor any kind of status indication. | ||
| + | |||
| + | The codes are SSH protocol codes (originally Telnet codes). | ||
| + | |||
| + | The ''12'' means "EOF" and is sent to indicate a close of the session. The ''15'' means "ping" and is used to [[ui_login_connection#keepalives|keep a session alive]]. | ||
| + | |||
| + | ===== [[no_mapping_for_unicode]] No mapping for the Unicode character exists in the target multi-byte code page -- The file must be in UTF-8 or UTF-16 encoding. ===== | ||
| + | |||
| + | You get this error message, when you try to execute a [[scripting#using_scripting|script]] that does not use a valid UTF-8 (or UTF-16) encoding. | ||
| + | |||
| + | Older versions of WinSCP used legacy ANSI encoding, when the script file does not have %%UTF-8%% (or UTF-16) byte order mark (BOM). The recent versions of WinSCP default to %%UTF-8%% encoding, when no BOM is present. If you have a script written in ANSI encoding for an old version of WinSCP, you have to convert it to %%UTF-8%% (or UTF-16) encoding, when upgrading to a recent version of WinSCP. | ||
| + | |||
| + | A simple way to convert the script encoding is: | ||
| + | |||
| + | * Open the script in Notepad; | ||
| + | * Go to //File > Save As//; | ||
| + | * Change //Encoding// from //ANSI// to //%%UTF-8%%//; | ||
| + | * Click //Save//. | ||
| + | |||
| + | ===== [[invalid_access_to_memory]] Invalid access to memory ===== | ||
| This error message is not useful for you as an end-user. It generally means that there is a bug in the software. Please [[reporting|report the bug]]. | This error message is not useful for you as an end-user. It generally means that there is a bug in the software. Please [[reporting|report the bug]]. | ||
| + | |||
| + | <nosplit> | ||
| + | ===== Other References ===== | ||
| + | SSH code of WinSCP is based on PuTTY. So if you are getting some error message while using [[protocols|SFTP or SCP protocols]] (particularly while connecting), you may check also the [[&url(puttydoc)/Chapter10.html|common error messages]] in PuTTY documentation. | ||
| + | </nosplit> | ||
| + | |||