Rsync: transfer hangs or freezes

Fix Rsync transfers that hang, freeze, or time out due to SSH idle timeouts, insufficient memory, firewall connection drops, and version mismatches.

When Rsync Produces This Error
What Causes a Hanging Transfer in Rsync
How to Fix a Hanging Transfer in Rsync
How to Verify the Fix
Edge Cases and Variations
Related Rsync Errors

Rsync produces a hanging or frozen transfer when the connection stalls, the system runs out of memory, or SSH terminates an idle session during a large file transfer.

When Rsync Produces This Error

Rsync hangs during a file transfer and appears to stop making progress. The terminal shows no new output, and the transfer does not complete or produce an error message. The process may eventually terminate with "connection unexpectedly closed" or "broken pipe" after an extended wait.

Rsync hangs during large file transfers (500 GB+) when the checksum or verification phase takes longer than the SSH idle timeout. The server-side Rsync process computes checksums while the client-side process waits. SSH interprets this idle period as inactivity and drops the connection.

Rsync hangs when a firewall or NAT gateway drops idle TCP connections. Stateful firewalls track connection state and silently discard connections that show no traffic for a configured period (typically 5-30 minutes).

What Causes a Hanging Transfer in Rsync

Rsync hangs when the SSH connection times out due to inactivity. SSH's ClientAliveInterval and ClientAliveCountMax settings on the server, or ServerAliveInterval on the client, determine how long an idle connection persists. Default SSH configurations may terminate idle connections after a few minutes.

Rsync hangs when the local or remote machine exhausts available memory. Rsync's memory usage scales with the number of files in the transfer. A transfer of millions of files can consume hundreds of megabytes of RAM. When the system runs out of memory, the kernel's OOM killer may stall or terminate the Rsync process.

Rsync hangs when incorrect command-line options cause unexpected behavior. Omitting the -P or --partial flag means Rsync deletes partially transferred files on interruption, requiring a full re-transfer. Without --timeout, Rsync waits indefinitely for unresponsive connections.

Rsync hangs when the local and remote Rsync versions have incompatible protocol implementations. Version mismatches can cause the sender and receiver to enter a deadlock state while negotiating the transfer.

How to Fix a Hanging Transfer in Rsync

Add SSH keepalive optionsto prevent idle connection timeouts. Pass ServerAliveInterval and ServerAliveCountMax to SSH via the -e flag.
```
rsync -avz -e "ssh -o ServerAliveInterval=60 -o ServerAliveCountMax=3" /home/user/src/ user@203.0.113.10:/home/user/dest/
```
Rsync instructs SSH to send a keepalive packet every 60 seconds. SSH disconnects if 3 consecutive keepalives receive no response (3 minutes of total inactivity).
Configure the SSH serverto send keepalive packets from the server side. Edit /etc/ssh/sshd_config on the remote machine.
```
TCPKeepAlive yes
ClientAliveInterval 60
ClientAliveCountMax 10
```
Restart the SSH daemon to apply the changes.
=== "Ubuntu / Debian"
```
sudo systemctl restart sshd
```
=== "CentOS / RHEL"
```
sudo systemctl restart sshd
```
Rsync transfers over SSH benefit from both client-side and server-side keepalive settings. The server sends a keepalive every 60 seconds and allows 10 missed responses (10 minutes of inactivity).
Set an Rsync I/O timeoutto detect and abort stalled transfers. The --timeout flag specifies the maximum seconds Rsync waits for I/O activity before exiting.
```
rsync -avz --timeout=300 /home/user/src/ user@203.0.113.10:/home/user/dest/
```
Rsync exits with an error if no data is transferred within 300 seconds. This prevents indefinite hangs.
Add the -P flagto keep partial files and show transfer progress. Rsync resumes interrupted transfers from the last partial file instead of re-transferring everything.
```
rsync -avzP /home/user/src/ user@203.0.113.10:/home/user/dest/
```
Rsync displays a progress bar for each file and retains partial files on the destination. Rerun the same command to resume after a hang.
Check available memoryon both the local and remote machines. Rsync consumes memory proportional to the number of files and directories in the transfer.
```
free -h
```
Rsync requires sufficient free memory to build its file list in RAM. For transfers with millions of files, increase available memory or break the transfer into smaller batches using --include and --exclude filters.
Use compressionto reduce the amount of data transmitted and decrease the time the connection sits idle.
```
rsync -avz --compress-level=6 /home/user/src/ user@203.0.113.10:/home/user/dest/
```
Rsync compresses data blocks before sending them. The --compress-level flag accepts values from 0 (no compression) to 9 (maximum compression).
Update Rsyncon both the local and remote machines. Older Rsync versions contain bugs that cause protocol deadlocks and hanging transfers.
```
rsync --version
ssh user@203.0.113.10 "rsync --version"
```
=== "Ubuntu / Debian"
```
sudo apt update && sudo apt install --only-upgrade rsync
```
=== "CentOS / Fedora / RHEL"
```
sudo dnf update rsync
```

How to Verify the Fix

Rsync completes the transfer without hanging when the fixes are applied. Run the transfer with verbose output and a timeout to confirm stable behavior.

rsync -avzP --timeout=300 -e "ssh -o ServerAliveInterval=60 -o ServerAliveCountMax=3" /home/user/src/ user@203.0.113.10:/home/user/dest/

Rsync prints the file list, progress bars, and a summary line showing total bytes sent and received. A clean completion without hanging confirms the fix.

Monitor active Rsync processes on the local machine during the transfer.

ps aux | grep rsync

Edge Cases and Variations

Rsync hangs at the end of a large transfer during the post-transfer verification phase. Rsync computes checksums on both sides after copying all files. This phase produces no network I/O, which triggers SSH idle timeouts. Increase ServerAliveInterval and ClientAliveInterval to values that exceed the expected verification time.

Rsync hangs when transferring files through a VPN tunnel with a low Maximum Transmission Unit (MTU). Packet fragmentation causes TCP retransmissions that stall the transfer. Reduce the MTU on the VPN interface or add --bwlimit to slow the transfer rate below the VPN's effective throughput.

Rsync hangs when the --delete flag is combined with a very large file tree. Rsync builds the complete file list in memory before starting deletions. Break the transfer into smaller directory batches or use --delete-after to defer deletions until after the transfer completes.

Rsync hangs on systems with aggressive power management that suspend network interfaces during periods of low activity. Disable network interface power management with ethtool -s eth0 wol g or equivalent settings.

Related Rsync Errors

Rsync: error in rsync protocol data stream-- network drops and SSH timeouts that cause hanging transfers also produce protocol data stream errors.

Rsync: failed to set permissions on-- permission errors may appear alongside hanging transfer issues when the destination filesystem is incompatible.