Differences
This shows you the differences between the selected revisions of the page.
| messages 2020-05-23 | messages 2024-05-14 (current) | ||
| Line 6: | Line 6: | ||
| ===== [[host_key]] Continue connecting to an unknown server and add its host key to a cache? ===== | ===== [[host_key]] Continue connecting to an unknown server and add its host key to a cache? ===== | ||
| - | This error message occurs 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. | + | 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(message_host_key) | + | &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 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)) | ||
| - | Both SHA-256 and MD5 fingerprints of the host key are shown. As both fingerprints are for the same key, it is enough to check only one of them. Checking %%SHA-256%% fingerprint is safer though. | + | 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 the [[faq_hostkey|host key fingerprint is correct]], press //Yes//. 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), press //No//. 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. |
| - | + | ||
| - | If you have the correct host key (or its fingerprint) in a digital form, instead of checking the fingerprint manually, you can use //Paste Key// button (in drop·down menu of //Yes// 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 the fingerprints to clipboard. | + | |
| + | 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]]. | Read more about [[ssh_verifying_the_host_key|verifying host keys]]. | ||
| Line 26: | Line 23: | ||
| ===== [[security_breach]] Warning -- Potential security breach! ===== | ===== [[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.· | + | 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. |
| - | This 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, use //Add// button to build a list of known host keys, instead of using //Update//. | + | 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)) | 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)) | ||
| Line 34: | Line 35: | ||
| Read more about [[ssh_verifying_the_host_key|verifying host keys]]. | Read more about [[ssh_verifying_the_host_key|verifying host keys]]. | ||
| - | ===== [[connection_refused]] Network error: Connection refused ===== | + | ==== [[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: | You may get this message when connecting to a server for the following reasons: | ||
| - | * 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 [[guide_exchange|FAQ]]. | + | * 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 [[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%%. | + | * 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]]. | + | * 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. | * 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|FAQ]]. | * Connection was blocked by the firewall. Please refer to [[faq_connection_refused|FAQ]]. | ||
| Line 46: | Line 59: | ||
| ==== In Other Languages ==== | ==== In Other Languages ==== | ||
| - | * //Deutsch// -- Netzwerkfehler: Verbindung abgelehnt | + | * //Deutsch// -- Netzwerkfehler: Verbindung zum Host „...“ wurde abgelehnt |
| - | * //Español// -- Error de Red: Conexión Rechazada | + | * //Español// -- Error de red: conexión a «...» rechazada. |
| - | * //Français// -- Erreur réseau : connexion refusée | + | * //Français// -- Erreur réseau : connexion à l'hôte "..." refusée. |
| - | * //Italiano// -- Errore di rete: connessione rifiutata | + | * //Italiano// -- Errore di rete: connessione a "..." rifiutata. |
| ===== [[connection_refused_ftp]] No connection could be made because the target machine actively refused it ===== | ===== [[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"]]. | The same as [[message_connection_refused|"Network error: Connection refused"]]. | ||
| - | ===== [[connection_timed_out]] Network error: Connection timed out ===== | + | ===== [[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. | All reasons and hints for [[message_connection_refused|"Network error: Connection refused"]] apply to this error too. | ||
| Line 79: | Line 92: | ||
| You need to select FTP protocol explicitly on [[ui_login|Login dialog]]. | You need to select FTP protocol explicitly on [[ui_login|Login dialog]]. | ||
| - | ===== [[no_route_to_host]] Network error: No route to host ===== | + | ===== [[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. | 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. | It may also be worth trying again later as this error can be due to temporary network issue. | ||
| Line 100: | Line 113: | ||
| Learn about [[ftp_modes|FTP connection modes and required network configuration]]. | 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 ===== | ===== [[software_caused_connection_abort]] Network error: Software caused connection abort ===== | ||
| + | |||
| ==== While Connecting ==== | ==== While Connecting ==== | ||
| 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: | ||
| Line 110: | Line 126: | ||
| 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. | 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. | ||
| - | 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 SSH-2 and WinSCP attempts a [[ui_login_kex#reexchange|key re-exchange]]. | + | 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]]. |
| 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]]. | 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]]. | ||
| Line 118: | Line 134: | ||
| 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. | 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 ===== | + | ===== [[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. | ||
| Line 125: | Line 141: | ||
| * Problem with DNS server. | * 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%%''). | * 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|Why does WinSCP not work in a new environment (operating system, machine, user account, network), when it works for me in a different environment already?]] | + | * 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. | * Server IPv6 address might by misconfigured. Try forcing IPv4 in //[[ui_login_connection|Internet protocol version]]// session settings. | ||
| Line 179: | Line 195: | ||
| To disable the stateful %%FTP%% filtering, in an Administrator command prompt, execute following command: | To disable the stateful %%FTP%% filtering, in an Administrator command prompt, execute following command: | ||
| - | <code> | + | <code batch> |
| - | netsh advfirewall set global StatefulFTP disable | + | netsh advfirewall <nohilite>set</nohilite> global StatefulFTP disable |
| </code> | </code> | ||
| - | For details refer to [[https://docs.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]]. | + | 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 ===== | ===== 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. | 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-2 encryption keys]]// or //[[ui_login_bugs#sshbug_maxpkt2|Ignores SSH-2 maximum packet size]]// session option. | + | 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. | 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. | ||
| Line 202: | Line 218: | ||
| 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. | 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]]//. | 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. | Some users also experience this message, when they run out of disk space/quota on the server. | ||
| Line 212: | Line 242: | ||
| * //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 ! | * //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! | * //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 ===== | ===== [[access_denied]] Access denied ===== | ||
| You will get the error while authenticating when: | You will get the error while authenticating when: | ||
| * You have entered incorrect password, used non-authorized key, etc. | * 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 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 (username) you have entered on Login dialog does not exist at all. | ||
| * The account is disabled. | * The account is disabled. | ||
| Line 226: | Line 258: | ||
| If you are not controlling the server, seek help with your server administrator (e.g. your webhosting provider). | If you are not controlling the server, seek help with your server administrator (e.g. your webhosting provider). | ||
| - | See also [[faq_username|Where do I get a username and password?]] | + | See also [[faq_username|*]] |
| ===== [[key_refused]] Server refused our key ===== | ===== [[key_refused]] Server refused our key ===== | ||
| Line 233: | Line 265: | ||
| 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)) | 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|set up SSH public key authentication]]. | + | Learn how to [[guide_public_key|*]]. |
| ===== [[permission_denied]] Permission denied ===== | ===== [[permission_denied]] Permission denied ===== | ||
| - | You do not have a sufficient permissions (access rights) to a resource, such as a file or directory, to perform the operation. | + | 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. | You should contact the server administrator to resolve the problem. | ||
| Line 256: | Line 288: | ||
| If you see one of these messages, it often indicates that you've tried to load a key of an inappropriate type into WinSCP. | 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 (or vice versa). | + | 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 an SSH-2 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)) | + | 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 '...' ===== | ===== [[unexpected_directory_listing]] Unexpected directory listing line '...' ===== | ||
| Line 367: | Line 399: | ||
| * 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. | * 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 [[ui_pref_resume|transfer resume/transfer to temporary filename]]. | + | 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. ===== | ===== [[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. ===== | ||
| Line 379: | Line 415: | ||
| Note that you cannot disable preserving timestamp for [[task_synchronize|synchronization]], unless you turn off //Modification timestamp// [[ui_synchronize#criteria|comparison criteria]]. | Note that you cannot disable preserving timestamp for [[task_synchronize|synchronization]], unless you turn off //Modification timestamp// [[ui_synchronize#criteria|comparison criteria]]. | ||
| - | ==== Scripting ==== | + | ==== [[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). | 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]]'' is ''none'' or ''size'' and it never works in ''both'' mode. | + | With [[scriptcommand_synchronize|''synchronize'' command]], this works only when ''[[scriptcommand_synchronize#criteria|-criteria]]'' lacks ''time'' and it never works in ''both'' mode. |
| - | ==== .NET Assembly ==== | + | ==== [[library]] .NET Assembly ==== |
| When using [[library|.NET assembly]], set ''[[library_transferoptions|TransferOptions]]'' as shown in following examples: | When using [[library|.NET assembly]], set ''[[library_transferoptions|TransferOptions]]'' as shown in following examples: | ||
| Line 407: | Line 443: | ||
| </code> | </code> | ||
| - | With [[library_session_synchronizedirectories|''Session.SynchronizeDirectories'']], this works only when ''criteria'' parameter is ''SynchronizationCriteria.None'' or ''SynchronizationCriteria.Size'' and it never works when ''mode'' parameter is ''SynchronizationMode.Both'' (learn [[library_powershell#enums|enumeration syntax]] in PowerShell). | + | 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 ==== | ==== In Other Languages ==== | ||
| Line 421: | Line 457: | ||
| This error is returned by Windows IIS server due to a known bug. | This error is returned by Windows IIS server due to a known bug. | ||
| - | For details see [[https://support.microsoft.com/en-us/help/2888853/fix-the-supplied-message-is-incomplete-error-when-you-use-an-ftps-clie|Microsoft KB 2888853]]. | + | 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 ===== | ===== [[library_process_terminated_with_exit_code_3]] WinSCP process terminated with exit code 3 ===== | ||
| - | This error comes in variants: | + | 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."// |
| - | * //WinSCP process terminated with exit code 3 and output %%""%%, without creating a log file.// | + | |
| - | * //WinSCP process terminated with exit code 3 and output %%""%%, without responding.// | + | |
| 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]]. | 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]]. | ||
| Line 443: | Line 477: | ||
| * 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 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]]. | * 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]]. | * 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]]. | ||
| Line 454: | Line 489: | ||
| ===== [[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) ===== | ===== [[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 and extracted using Windows File Explorer. These applications, under certain circumstances, block libraries downloaded from Internet as potentially harmful, what prevents their loading. | + | 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. You may need to restart your IDE (if any), for the change to apply. | + | 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. ===== | ===== [[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]]. Alternatively, you can [[library_ssis#subscribe|subscribe ''AppDomain.AssemblyResolve'' event]] to allow loading the assembly. | + | 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://docs.microsoft.com/en-us/dotnet/framework/tools/fuslogvw-exe-assembly-binding-log-viewer|Assembly Binding Log Viewer]] (''Fuslogvw.exe'') to debug assembly loading. | + | 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. ===== | ===== [[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. ===== | ||
| Line 481: | Line 518: | ||
| This is just a high-level exception. The root cause is usually stored in the ''[[dotnet>system.exception.innerexception|InnerException]]''. | 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]]. | + | 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 cannot access the inner exception easily, inspect WinSCP session log and debug log file (''[[library_session#sessionlogpath|Session.SessionLogPath]]'', ''[[library_session#debuglogpath|Session.DebugLogPath]]''). If those file are not even created, 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 ===== | ===== [[sessionoptions_sshhostkeyfingerprint_is_not_set]] SessionOptions.Protocol is Protocol.Sftp or Protocol.Scp, but SessionOptions.SshHostKeyFingerprint is not set ===== | ||
| Line 502: | Line 539: | ||
| </code> | </code> | ||
| - | To learn how to find the value of the fingerprint see [[faq_hostkey|Where do I get SSH host key fingerprint to authorize the server?]] | + | 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''. | 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 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 and WebDAVS. | ||
| ===== [[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. ===== | ===== [[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. ===== | ||
| Line 561: | Line 629: | ||
| <nosplit> | <nosplit> | ||
| ===== Other References ===== | ===== Other References ===== | ||
| - | SSH code of WinSCP is based on PuTTY. So if you are getting some error message while using [[protocol|SFTP or SCP protocols]] (particularly while connecting), you may check also the [[&url(puttydoc)/Chapter10.html|common error messages]] in PuTTY documentation. | + | 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> | </nosplit> | ||