Skip to main content

SFTP Debugging

Step-by-step debugging for SFTP issues.

Connection Refused / Timed Out​

  1. Verify the public IP: curl https://checkip.amazonaws.com
  2. Ensure the IP is allowlisted: on a managed server, add it under Add Inbound IP Rule on the server's Security tab. On the agency's own server, allow the addresses listed under Whitelist IP Addresses on the server's Overview tab.
  3. Test port connectivity:
    • Linux/Mac: nc -zv {server_ip} 22
    • Windows: Test-NetConnection -ComputerName {server_ip} -Port 22
  4. Test network reachability: ping {server_ip}
  5. Check that SFTP port is open in the outbound firewall

Permission Denied / Authentication Failed​

  1. Verify username is correct
  2. Ensure password field is blank when using key-based auth
  3. Check private key permissions: chmod 400 {key.pem} (Linux/Mac)
  4. For Windows:
icacls "%USERPROFILE%\.ssh\key.ppk" /inheritance:r
icacls "%USERPROFILE%\.ssh\key.ppk" /grant:r "%username%:(R)"
  1. Ensure private key format matches client (PEM for OpenSSH, PPK for PuTTY/WinSCP)

Debug Logging​

  • OpenSSH: ssh -i "path/to/key.pem" user@hostname -vvv
  • WinSCP: WinSCP.exe /log="path/to/logfile.log" /loglevel=5
  • GUI clients: Enable debug logging in Options/Preferences > Logging

Files Not Processing​

  1. Check Auto Sync Enabled is checked on the profile's Settings tab. A profile with Auto Sync off shows a yellow Auto Sync Disabled badge.
  2. Verify the Source Directory. For a profile linked to a server, it is relative to the server's Source Directory (for example, incoming, not /home/ubuntu/incoming).
  3. Confirm the file sits directly in the Source Directory. Subdirectories are not scanned.
  4. Check the file name contains the Filename Keyword (if set) and does not contain the Filename Blockword. Matching ignores case.
  5. Check no earlier upload in the agency has the same file name. A matching name is skipped as a duplicate.
  6. Check an Upload Template is selected. A profile without one uploads nothing.

Expected Port Test Results​

  • Success: port shows "open" or "succeeded"
  • Connection refused: SFTP service not running on server
  • Connection timed out: IP not whitelisted or firewall blocking

Getting Help​

To request help, create a support ticket in the Console: sign in, click the Help button in the bottom-right corner, and complete the Create a Ticket form (Region, Agency, Feature, and a Description). The current page is attached automatically, and updates appear under My Tickets in the same panel.

In the description, include the server name and Host, the connecting IP addresses, the full error text, the SFTP client and version, and the relevant debug logs.

danger

Never share passwords, SSH private keys, or private key contents in a support ticket or logs.

See also: SFTP Troubleshooting, SFTP Errors