Troubleshooting Common X-WinSCP Connection IssuesX-WinSCP is a powerful graphical client for secure file transfers using protocols like SFTP, SCP, FTP, and WebDAV. Despite its reliability, users occasionally encounter connection problems that can interrupt workflows. This guide covers common connection issues, how to diagnose them, and practical steps to resolve each problem.
1. Verify basic network connectivity
Before digging into X-WinSCP settings, confirm the network path between your machine and the server:
- Ping the server hostname or IP to check basic reachability:
ping example.com
- Use
tracert
(Windows) ortraceroute
(Linux/macOS) to find routing issues. - Ensure no local firewall or network policy blocks outbound connections.
If ping/traceroute fail, address general network or DNS issues first; X-WinSCP-specific fixes won’t help until the server is reachable.
2. Check host, port, and protocol settings
A surprisingly common cause of failed connections is incorrect session details.
- Ensure the hostname or IP address is correct.
- Confirm the port number matches the service (default: 22 for SFTP/SCP, 21 for FTP, 443 or custom for WebDAV over HTTPS).
- Choose the correct protocol in X-WinSCP (SFTP vs FTP vs WebDAV).
- If the server uses a non-standard port, enter it explicitly.
Tip: If you can SSH to the server from a terminal (e.g., ssh [email protected] -p 2222
), use the same details in X-WinSCP.
3. Authentication failures (passwords, keys, and agents)
Authentication errors are frequent. Steps to resolve:
- Re-enter username and password to rule out typos.
- If using SSH keys, verify the correct private key is selected in Session → Advanced → Authentication. X-WinSCP supports PuTTY PPK keys and OpenSSH keys (convert if necessary).
- Check file permissions on the private key: some servers reject keys with permissive permissions (e.g., ensure private key is not world-readable).
- If using Pageant (PuTTY agent), confirm the key is loaded. If using OpenSSH agent, ensure agent forwarding and key availability.
- For password-based logins, confirm the server allows password authentication (some servers require keys only).
Error examples and actions:
- “Authentication failed.” — try password reset or verify key pairing.
- “Server refused our key” — ensure public key is in server’s authorized_keys and permissions are correct.
4. Host key verification and unknown host key errors
On first connection, X-WinSCP shows the server’s host key fingerprint. Problems arise when the host key changes or is mismatched.
- If you see a warning about a different host key, do not ignore it—this can indicate a man-in-the-middle attack or legitimate server reinstallation.
- Verify the new fingerprint through a trusted channel (server admin, control panel). If valid, update the stored host key in X-WinSCP’s known hosts by confirming the new fingerprint.
- To view and manage host keys: Session → Advanced → SSH → Authentication → Host key.
5. Timeouts and slow connections
Long response times or timeouts can be due to network latency, server load, or keepalive settings.
- Increase timeout values: Session → Advanced → Connection → Timeout.
- Enable keepalives: Session → Advanced → Connection → Sending of null packets (keepalives) or enable TCP keepalives to prevent sessions from being dropped by intermediate NAT/firewall.
- Test network latency (
ping
orpathping
) and server load (top
,htop
on the server). - If transfers are slow but the connection is stable, consider adjusting transfer settings (number of concurrent transfers, encryption algorithms).
6. Firewall, NAT, and passive/active FTP mode
For FTP connections, firewalls and NAT often cause problems.
- Switch between Passive and Active FTP modes: Session → Advanced → FTP → Passive mode. Passive mode usually works better behind NAT.
- Ensure necessary ports are open: FTP control (21) and passive data port range configured on server and allowed through firewalls.
- For SFTP/SSH, ensure port 22 (or custom SSH port) is allowed through firewalls and not intercepted.
7. Cipher and protocol mismatches
Servers sometimes disable older ciphers or protocols for security, and X-WinSCP may attempt incompatible settings.
- Update X-WinSCP to the latest version to ensure support for modern ciphers.
- Check server-side SSH configuration (sshd_config) for allowed ciphers and KEX algorithms.
- In X-WinSCP: Session → Advanced → SSH → Encryption and Key Exchange to adjust the order or disable deprecated algorithms.
- Review server logs for messages about rejected algorithms.
8. Permissions and filesystem errors
After connecting, you may face errors when listing directories or transferring files.
- Verify the account’s filesystem permissions on the server (read/write/execute).
- Ensure the server’s disk is not full: check
df -h
. - If encountering “permission denied” on upload, confirm target directory ownership and modes.
- For SFTP chrooted environments, ensure the chroot directory has proper ownership (usually root) and writable subdirectory for the user.
9. Proxy and jump hosts (bastion) configurations
If your server is behind a bastion or requires a proxy, configure X-WinSCP accordingly.
- For SSH jump hosts: Session → Advanced → SSH → Tunneling or use ProxyCommand (
ssh -W
) if your environment supports it. - For HTTP or SOCKS proxies: Session → Advanced → Connection → Proxy. Provide proper proxy type, host, port, and credentials.
- Test direct SSH to the final host via the jump host from a terminal to validate the chain before configuring X-WinSCP.
10. Logging and detailed diagnostics
Use logging to capture errors and help diagnose subtle issues.
- Enable session logging: Session → Logging → Enable session logging. Choose a file and log level.
- Review server-side logs (e.g., /var/log/auth.log or /var/log/secure) for SSH/SFTP messages.
- Compare timestamps between client logs and server logs to correlate failures.
11. Common error messages and quick fixes
- “Network error: Connection timed out” — check host/port, firewall, increase timeout.
- “Connection refused” — service not running or wrong port. Start server service (sshd, vsftpd) or fix port.
- “Authentication failed” — wrong credentials, wrong key, or server only allows key authentication.
- “Host key verification failed” — verify host key fingerprint and update known hosts if legitimate.
- “Transfer interrupted” — check keepalives, network stability, and server load.
12. When to contact the server administrator
Contact the admin if:
- You cannot reach the server at all (ping/traceroute fail).
- Host key changed unexpectedly and cannot be verified.
- Server-side logs show errors you can’t interpret (provide logs).
- Server requires configuration changes (open ports, adjust chroot, add public key).
When contacting, supply: timestamp, client log excerpt, server hostname/IP, username, and the exact error message.
13. Preventive measures and best practices
- Keep X-WinSCP updated.
- Use SSH keys instead of passwords and protect private keys with passphrases.
- Store verified host key fingerprints in a secure place.
- Enable logging for intermittent issues.
- Use version control or scripts for automated transfers to reduce manual error.
Troubleshooting X-WinSCP is mostly systematic: verify basic network reachability, confirm session settings, check authentication and host keys, inspect firewalls/proxies, and use logs on both client and server. Addressing each layer—network, transport, authentication, and application—quickly narrows down the cause and leads to a fix.