Guide

SFTP timeout troubleshooting: causes and fixes

SFTP timeouts come in a few distinct flavours, connection, idle, and large-listing. Here's how to tell them apart and fix each, from firewall and keepalive settings to huge directory listings.

“SFTP timed out” can mean several very different things, and the fix depends on which timeout you hit. Work out which of these it is and the cause is usually obvious.

1. Connection timeout (can’t connect at all)

The client hangs at “Connecting…” and gives up. The SFTP session never even starts.

Likely causes:

  • A firewall blocking the port (SFTP is usually TCP 22) outbound from the client or inbound to the server.
  • Wrong hostname or port.
  • The server is down or unreachable.

Fixes: test raw reachability with nc -vz host 22 or ssh -v user@host. If the port is filtered, open it in the firewall (or confirm the partner’s egress allows 22). Confirm the hostname resolves and the service is up.

2. Authentication hang

You connect, but it stalls during login.

Likely causes: the client is offering the wrong key and waiting, or trying many auth methods. Occasionally a reverse-DNS lookup on the server side adds delay.

Fixes: specify the exact key with -i ~/.ssh/yourkey so the client doesn’t cycle through options, and confirm the public key is actually registered for that user.

3. Idle timeout (drops after a quiet period)

The session works, then drops if it sits idle, common behind NAT and load balancers that reap idle connections.

Fix: enable SSH keepalives so the connection stays warm:

sftp -o ServerAliveInterval=30 -o ServerAliveCountMax=4 user@host

Or set ServerAliveInterval 30 in ~/.ssh/config.

4. Large-directory-listing timeout

The session is fine until you ls a directory with a huge number of files, then it hangs or errors. This is specific to object-storage-backed SFTP: listing a prefix with hundreds of thousands or millions of keys means a large, slow live enumeration of the bucket.

Fixes:

  • Spread very large object counts across sub-folders rather than one flat directory.
  • Use a gateway that fails loudly on an oversized listing rather than hanging or returning a silent partial list.
  • If you regularly list huge prefixes, enable the gateway’s optional synced index, which keeps listings fast at scale (it’s opt-in, not on by default). Firepipe’s behaviour here is documented on the SFTP compatibility page.

5. Transfer stalls mid-file

A large upload or download starts, then freezes partway.

Likely causes: an unstable network, or an intermediate device dropping a long-lived connection.

Fixes: use a client that resumes (so a drop doesn’t restart from zero), enable keepalives as above, and for very large files prefer a client and gateway that do multipart with resume.

Quick triage

  • Never connects → firewall / port / host (cause 1).
  • Hangs at login → key / auth (cause 2).
  • Drops when idle → keepalives (cause 3).
  • Dies on a big ls → directory size / listing (cause 4).
  • Freezes mid-transfer → network / resume (cause 5).

To run SFTP cleanly in front of your own cloud bucket, see SFTP to S3.

Try it on your own bucket

Connect a bucket you already own, Amazon S3, Azure Blob, Google Cloud Storage, or an S3-compatible store, and hand out a clean SFTP endpoint in minutes. Your files stay in your cloud.

Start free

← All guides