SFTP Troubleshooting
Use the commands and techniques on this page to diagnose SFTP connectivity issues.
Finding the IP addresses
Most firewall and allowlist issues come down to two IP addresses: the server's IP and the connecting machine's IP.
Server IP (managed server): Open the server in the Console. On the Overview tab, the Host field shows the server's IP or hostname. For a managed server, the EC2 details also show the Public IP. This is the connection target.
The connecting IP (to allowlist on a managed server): On the server's Security tab, the Add Inbound IP Rule form shows the IP address the Console is being used from ("Your current IP is <ip>/32"). Enter the address on its own or with /32 when adding a rule. See Managed Server.
eCourtDate's connecting IP (the agency's own server only): This applies only when eCourtDate connects to a server the agency runs. eCourtDate connects from a fixed set of IPs, shown in the Console under Whitelist IP Addresses on the server's Overview tab. Allowlist the values shown in the Console on the server's firewall. With a managed server these do not apply: only the connecting machine's IP is added on the Security tab.
Fallback only: To find the public IP of a different machine that the Console cannot show (for example, a separate case management server), look it up from that machine:
curl https://checkip.amazonaws.com
On Windows PowerShell:
(Invoke-WebRequest -Uri "https://checkip.amazonaws.com").Content
Checking a managed server's status
For a managed server, confirm the server is running before digging into client or network issues. Open the server in the Console. On the Overview tab, the instance card shows the instance state as a badge (for example, Running) next to the instance ID, with Instance Details and Network Information (including the Public IP) below. If the state is not Running, the server cannot accept connections; open a support ticket so eCourtDate can start it.
Click Test connection on the server page to verify that the Console can reach the server. A successful test reads "Connection successful" followed by the host and response time. A failure reads Unable to connect, which points to the server, its firewall rules, or the network rather than the local client. The test gives up after 5 seconds, whatever the server's Timeout setting. After a successful test, if connections still fail from the agency's own machine, the cause is the client, the credentials, or an IP address that is not allowlisted. See Managed Server.
Port Connectivity Testing
Test whether the SFTP port is reachable from the machine.
Linux / macOS:
nc -zv {server_ip} 22
Windows PowerShell:
Test-NetConnection -ComputerName {server_ip} -Port 22
All platforms:
ping {server_ip}
Interpreting Results
| Result | Meaning |
|---|---|
| Port is open / connection succeeded | The SFTP service is reachable, so the failure is in authentication. See Authentication errors and SFTP Errors. |
| Connection refused | The connecting IP is not allowlisted on the server firewall. See Finding the IP addresses. For a managed server, add the IP under Add Inbound IP Rule on the server's Security tab. |
| Timed out | The connecting IP is not allowlisted on the server firewall, or a network-level firewall is blocking the connection. See Finding the IP addresses. For a managed server, add the IP under Add Inbound IP Rule on the server's Security tab. |
Authentication Errors
"Permission denied" / "Authentication failed" / "Server refused our key"
The server rejected the login credentials.
Confirm the use of the correct username. For a managed server, connect as ubuntu (listed in the Connection section of the server's Settings tab in the Console). For the agency's own server, use the username configured on that server.
When using an SSH private key:
- Ensure the password field is blank in the SFTP client when the server expects key-based authentication.
- Ensure the key passphrase is blank or disabled unless the server requires one.
- Restrict the private key to user read-only permissions. On Linux and macOS, run
chmod 400 path/to/key.pem. On Windows, see Windows Private Key Security.
See Authentication for key format and client setup, and SFTP Errors for other connection errors.
Debug Logging
Enable verbose logging in the SFTP client to capture detailed connection information for troubleshooting.
OpenSSH (Linux / macOS)
Standard verbosity:
ssh -i "path/to/key.pem" user@hostname -v
Maximum verbosity:
ssh -i "path/to/key.pem" user@hostname -vvv
WinSCP
Launch WinSCP with logging enabled:
WinSCP.exe /log="path/to/logfile.log" /loglevel=5
Or enable logging from within the application: Options > Logging > set log level to Debug.
PuTTY
Use the plink command-line tool with verbose output:
plink -i "path/to/key.ppk" user@hostname -v
GUI Clients
Most GUI SFTP clients provide a logging or debug option in their settings:
| Client | Path to Logging |
|---|---|
| WinSCP | Options > Logging |
| Transmit | Options > Logging |
| FileZilla | Edit > Settings > Logging |
| Cyberduck | Preferences > Connection > Log |
| FTPRush | Options > Logging |
Set the log level to Debug for the most detailed output.
Windows Private Key Security
On Windows, the private key file must be restricted so that only the user account can read it. Run the following commands in PowerShell or Command Prompt:
icacls "%USERPROFILE%\.ssh\key.ppk" /inheritance:r
icacls "%USERPROFILE%\.ssh\key.ppk" /grant:r "%username%:(R)"
The first command removes inherited permissions. The second grants read-only access to the user account. Replace key.ppk with the actual filename of the private key.
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:
- Server: the server name and its Host (shown on the server's Overview tab in the Console).
- Connecting IP addresses: the public IP of the machine or service connecting to the server.
- Error messages: the full text of any error messages shown.
- SFTP client used: the name and version of the SFTP client (e.g., OpenSSH 9.0, WinSCP 6.1, PuTTY 0.79).
- Debug logs: the relevant debug log output.
- The approximate time of the failed connection (an exact UTC timestamp is not required).
Check status.ecourtdate.com for platform incidents and scheduled maintenance.
Never share passwords, SSH private keys, or private key contents in a support ticket or logs. Remove or redact them before attaching logs.