Something went wrong — start here

What did you see?

• The transfer stops partway through, or the connection closes
• rsync appears to hang and does nothing
• It copies the same files every single time
• “is your shell clean”, or “protocol mismatch”
• “rsync: command not found”
• It uses a lot of memory, or runs out of it
• Filenames with spaces arrive as several files
• Rarer errors with specific causes

The transfer stops partway through

You will have seen one of these, usually with an error code of 12:

rsync: error writing 4 unbuffered bytes - exiting: Broken pipe
rsync error: error in rsync protocol data stream (code 12) at io.c(463)

rsync: connection unexpectedly closed (24 bytes read so far)
rsync error: error in rsync protocol data stream (code 12) at io.c(342)

This means the local rsync was talking to the remote one and that connection is now gone. The error itself never says why, so the job is to find out. The common causes, roughly in order:

• The destination disk is full. You need at least as much free space as the largest single file being updated.
• An idle connection was closed by a router or the remote SSH server. Add --timeout so rsync gives up cleanly, configure SSH keep-alives (ServerAliveInterval, ClientAliveInterval), or switch --delete for --del so deletions happen during the transfer instead of in one long silent pass before it.
• A network error dropped the connection.
• The remote rsync was not found — see command not found.
• Your remote shell is not clean — see is your shell clean.

First, get the errors somewhere you can read them. By default rsync tries to send messages down the pipe that is failing, so they are lost exactly when you need them:

$ rsync -av --msgs2stderr -M--msgs2stderr src/ HOST:dst/

Then check that the plumbing works at all, independently of rsync:

# must print exactly 'hi' and nothing else
$ echo hi | ssh HOST cat

# must start the remote rsync and report its version
$ ssh HOST rsync --version

If the remote end is a daemon rather than SSH, read its log file first — and check the log file setting in rsyncd.conf, since a wrong one produces this same error. You can also stop the daemon and run it with --no-detach --msgs2stderr and watch while someone retries the copy.

rsync appears to hang

Before you kill it, collect the two things that make the difference between a report someone can act on and one they cannot: the send and receive queue state from netstat at both ends, and which system call each of the three rsync processes is stuck in (strace on Linux, truss on Solaris).

Adding --msgs2stderr -M--msgs2stderr sometimes stops the hang by itself. And if you are passing more than one -v, stop: the flood of debug messages fills the same pipeline the transfer needs. Use -i (--itemize-changes) instead when you want to know what rsync is doing and why.

It copies the same files every time

Almost always one of four things:

• You left out -t. Without modification times, rsync has to check every file that might differ. Using -a includes -t and is the reason to default to it.
• You are writing to a Microsoft filesystem. If a file's modification time is an odd number of seconds and the receiving filesystem can only store even values, every file looks changed. Add --modify-window=1.
• Daylight saving just changed and your filesystem stores times in local time rather than UTC.
• The filesystem is rewriting your filenames. Some change case; HFS+ on macOS decomposes UTF-8, so a name with an umlaut is stored as different bytes than you sent and rsync does not recognise it as the same file. With --delete on, it will remove its own earlier copy and write it again, every run. Tell rsync both character sets: --iconv=UTF-8,UTF8-MAC.

To find out which, ask rsync why it is transferring each file. In the itemised output, a t means the time differs and a row of plus signs means rsync thinks the file is not there at all:

$ rsync -ain src/ HOST:dst/
>f.st...... notes.txt
>f+++++++++ new-photo.jpg

--checksum (-c) will compare contents instead of times and avoid the re-copying, but it reads every byte on both sides — a fix for a broken clock, not a habit.

“is your shell clean” or “protocol mismatch”

Something in your .bashrc, .profile or .cshrc on the remote machine prints a message on every login — a banner, a fortune, a “welcome back”. That text lands in the middle of rsync's data stream and corrupts it. rsync detects it at startup and says so.

# should create an EMPTY file; anything in it is the problem
$ ssh remotesystem /bin/true > test.dat
$ wc -c test.dat
0 test.dat

If test.dat is not empty, read it: whatever is in there is what to remove from your startup files, or guard behind a check for an interactive shell. If you are using daemon syntax (host::path or rsync://) then no remote shell is involved at all and the fault is on the daemon side — check its logs.

“rsync: command not found”

The remote shell could not find rsync in its PATH. rsync has to be installed on both machines. Find out what the remote PATH actually is:

$ ssh HOST 'echo $PATH'

Then pick one of three fixes: install rsync somewhere already on that PATH, add its location to the remote startup files, or just tell rsync where it is:

$ rsync -av --rsync-path=/usr/local/bin/rsync src/ HOST:dst/

Memory use

Only the number of files matters here, not their size. rsync needs roughly 100 bytes per file, so 800,000 files costs about 80 MB; -H and --delete push it higher.

Versions before 3.0.0 built the entire file list up front and held it for the whole run. 3.0.0 introduced incremental recursion, which builds the list in chunks and keeps each only as long as it is needed — a dramatic reduction, but it requires 3.0.0 or newer at both ends and is switched off by some options. If you are hitting “out of memory” on a very large tree, check the versions at both ends first, then split the job into several runs over subdirectories.

Filenames with spaces

rsync handles spaces fine. The trouble is that a remote path is interpreted twice — once by your shell and again by the shell on the remote machine — so 'HOST:a long filename' arrives as a request for three files called a, long and filename. Quote it so that quoting survives the second shell too:

# quoting has to survive BOTH shells, so quote twice
$ rsync -av 'HOST:"a long filename"' /tmp/
$ rsync -av 'HOST:a\ long\ filename' /tmp/

This does not affect daemon mode (host::path), where no remote shell is involved.

Rarer errors with specific causes

vanished files warning, exit code 24

Files disappeared while rsync was copying them — normal when backing up a live system. If it is expected, wrap rsync in a script that treats exit code 24 as success, so a real failure still gets noticed.

Read-only file system when sending to a daemon

The module is read-only. Set read only = no for it in rsyncd.conf.

multiplexing overflow 101:7104843, or invalid message 101:7104843

One of the rsync processes was killed and the word “Kill” ended up inside the protocol stream. The error is a symptom; find out what is killing rsync — often the out-of-memory killer.

inflate (token) returned -5

A compression bug affecting files transferred with a block size of exactly 32816 bytes. Work around it with --block-size=33000, or upgrade the receiving side.

Running --daemon from cron misbehaves

On some systems cron hands rsync something that looks like a socket, so rsync concludes it was started from inetd. Redirect stdin from /dev/null in the cron job.

A chrooted daemon crashes on an LDAP lookup

A bug in some LDAP libraries when a name is looked up from inside a chroot. Work around it with --numeric-ids, turn chroot off, or remove the LDAP lookup.

Reaching the project

rsync is a volunteer project. There is no support desk and no company behind it — the mailing list and the issue tracker are the whole of it.

If it is a security issue, do not open a public issue

Asking a question

The rsync mailing list (rsync@lists.samba.org) is where developers and users both are, and it is the right place for “how do I…” and “is this a bug?”. Traffic runs between zero and twenty messages a day. The project suggests reading the archives — or the mail-archive copy — rather than subscribing from a mailbox that will not cope; your question may already be answered there.

If you only want to know when a new version is out, subscribe to rsync-announce instead. It carries release announcements and nothing else, a few times a month at most.

Reporting a bug

Work through this before you file, because it is what the maintainers ask for:

1. Reproduce it on the current release — 3.4.4. Bugs in older versions are often already fixed.
2. Check NEWS.md in git in case it is already fixed in the version under development.
3. Search the existing issues for it.
4. If you are unsure whether it is a bug at all, ask on the mailing list first. That is what it is for.
5. Then open an issue on GitHub. Patches are welcome attached to an issue or as a pull request — the project is explicit that pull requests are not required, because that is a lot of git knowledge to demand of someone reporting a bug.

Worth reading once in your life, and linked by the project for this purpose: Simon Tatham's How to Report Bugs Effectively.