Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

rsync "connection unexpectedly closed (0 bytes received so far)": find out why the remote rsync went away

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

When rsync stops at the start with rsync: connection unexpectedly closed (0 bytes received so far) followed by rsync error: error in rsync protocol data stream (code 12), the remote rsync never sent anything before the connection ended. The rsync project's own advice is that the local rsync "was trying to talk to the remote rsync, but the connection to that rsync is now gone" and that you must work out why. Test the remote shell first, then ask whether rsync even started on the other side.

What the error means

rsync uses a client and a server. Over a remote shell such as ssh, the client starts rsync on the remote machine and the two exchange data on that connection. The message comes from the rsync source when it reads end-of-file from the network in the middle of the protocol. The source prints connection unexpectedly closed followed by the number of bytes received so far in parentheses and then a second field in square brackets, then exits with error code 12.

The manual defines exit value 12 as "Error in rsync protocol data stream". The number of bytes received is how much the local side had read when the connection closed. The rsync FAQ gives an example with 24 bytes; zero means the local side had received nothing from the remote end. The exchange therefore failed at its start: the remote command did not run, it ran something that is not rsync, or the connection was cut straight away.

The rsync project's "current issues and debugging" page lists five common causes of a transfer dying:

  • The destination disk is full.
  • An idle connection caused a router or remote-shell server to close it.
  • A network error dropped the connection.
  • The remote rsync executable was not found.
  • The remote shell setup is not working or not "clean", meaning it sends spurious text to rsync.

Likely causes

Cause What you see How to confirm
rsync not installed, or not on the remote shell's path Fails at once with 0 bytes; the remote shell may print a command-not-found message ssh HOST rsync --version does not print a version
Remote shell prints text (startup files) Fails at once; sometimes a protocol mismatch or "is your shell clean" message ssh HOST /bin/true > out.dat makes a file that is not empty
Account runs a forced command or a restricted shell Works for other tools (sftp) but not rsync The account's ForceCommand or shell does not run the command you send
Destination disk full Listed by the rsync issues page as a cause of a transfer dying; that page does not say what byte count to expect df on the destination shows no free space
Idle connection or network drop Fails after a long quiet period; the issues page says switching from --delete to --del can avoid some lulls A pattern of failures after the same idle time
rsync daemon refuses (when :: or rsync:// is used) Fails at once The daemon's own log has the reason

Prove the cause before changing anything

All of these are read-only apart from the small test file in step 3.

1. Run rsync on the remote side through ssh.

ssh HOST rsync --version

The rsync issues and debugging page says this should "successfully start the remote rsync and report its version". If the command is not found, or the account cannot run it, you have found the cause.

2. Check that the shell does not add output.

echo hi | ssh HOST cat

The same page says this should "output just the string "hi" and nothing else".

3. Check the shell for stray output, using a scratch directory.

ssh HOST /bin/true > out.dat

The rsync manual says that if everything is working, out.dat "should be a zero length file". The manual says the file "contains some text or data" if it is not empty, and that you must work out what is producing it. Text there would corrupt the rsync stream. Run it from a scratch directory, because it creates out.dat in the current one.

4. Get the errors shown.

rsync -avn --stderr=all SRC HOST:DEST

-n is the dry run, which performs "a trial run with no changes made". The manual says --stderr=all writes all rsync messages (info and error) directly to stderr from all possible processes. It also says rsync "accepts the old --msgs2stderr and --no-msgs2stderr options" and "uses them when forwarding non-default settings to the remote side, in case the remote rsync is an older version". The rsync issues and debugging page gives the older form --msgs2stderr -M--msgs2stderr for the same purpose.

5. Watch ssh itself. The ssh manual describes -v as verbose mode: ssh prints debugging messages about its progress, which it says is helpful in debugging "connection, authentication, and configuration problems".

6. Check space and the daemon log. For a full-disk cause, run df -h against the destination (the df manual lists -h, --human-readable). If you use the :: or rsync:// syntax there is no remote shell. The issues and debugging page says to look at the daemon's log file first, and to check that the daemon's log file setting in rsyncd.conf is right.

Fix

rsync is missing or not on the path

The FAQ lists three fixes: install rsync in a standard location on the remote path, change the remote shell startup files to include the directory, or use --rsync-path. The manual describes --rsync-path=PROGRAM for "when rsync is not in the default remote-shell's path" and gives --rsync-path=/usr/local/bin/rsync as the example. The manual also notes that rsync must be installed on both machines.

For example, with a known path:

rsync -av --rsync-path=/usr/local/bin/rsync SRC HOST:DEST

First print and keep the current state with ssh HOST rsync --version (it should report the command as not found). Disruptive step: installing a package on a production server changes it. Do it in a maintenance window, using the package manager your distribution provides. To back out, remove the package you installed with the same package manager, then run the same test again.

Disruptive step: editing a remote startup file such as .bashrc affects every login for that account, including ones you do not know about. Save it first, on the remote host, as the account that rsync logs in as: cp -a ~/.bashrc ~/.bashrc.2026-11-20. The rsync manual and FAQ document no syntax check for a startup file, so test straight away with ssh HOST rsync --version. To back out, copy the saved file back over .bashrc under its original name, then run the test again.

The shell prints text

Disruptive step: removing output statements from a startup file affects every login for that account. Save each startup file you will change first, the same way as .bashrc above (for example cp -a ~/.profile ~/.profile.2026-11-20). Find the statements in the startup files (the manual names .cshrc and .profile, and the FAQ adds .bashrc) that write output for non-interactive logins. Remove or stop them from running for non-interactive logins. To back out, copy the saved file back under its original name. Repeat steps 2 and 3 until out.dat is empty.

A forced command or restricted account

The sshd_config manual says ForceCommand runs a given command "ignoring any command supplied by the client". An account with ForceCommand internal-sftp therefore runs the SFTP server in place of the rsync command you send, so rsync ends at once. Risk: loosening a restriction on a locked-down account widens what it can do. The server's administrator should decide this. Use an account whose configuration allows rsync. Before editing sshd_config, save it with cp -a /etc/ssh/sshd_config /etc/ssh/sshd_config.2026-11-20, then edit, then run sshd -t before any reload. To back out, copy /etc/ssh/sshd_config.2026-11-20 back over /etc/ssh/sshd_config, run sshd -t, and reload sshd with your distribution's service command.

Disk full

The issues and debugging page notes that you need at least the size of the largest file that needs updating available in free disk space.

Risk: deleting files to make room cannot be undone. Free space on the destination, or grow its filesystem. Before deleting, first run df -h against the destination and write the figures in a dated note, then list the exact files you plan to remove and check each one is not the only copy of data you need, and remove only those files. To back out a deletion, restore the files from a backup or another copy you made first; if none exists, do not delete them.

Idle connection or network drop

The issues and debugging page suggests --timeout, which the manual describes as "set I/O timeout in seconds", and ssh keepalives. The ssh_config manual says ServerAliveInterval "Sets a timeout interval in seconds after which if no data has been received from the server, ssh(1) will send a message through the encrypted channel to request a response from the server", with a default of 0, so no such messages are sent. Pass ssh options through -e, as in the manual's example -e 'ssh -p 2234'. For timers on firewalls and load balancers, see "Connections drop after a few idle minutes through a firewall or load balancer: idle timers and TCP keepalive".

Example (illustrative): a job on app01 pushes to store01 and logs rsync: connection unexpectedly closed (0 bytes received so far). ssh store01 rsync --version reports that the command cannot be found. After a rebuild, rsync was installed under /usr/local/bin, which is not on the non-interactive path. The administrator adds --rsync-path=/usr/local/bin/rsync to the job. A dry run with -n shows the file list, and the real run finishes.

Confirm the fix

  1. ssh HOST rsync --version prints a version.
  2. echo hi | ssh HOST cat prints only hi, and out.dat is empty.
  3. A dry run (-n) completes without the error.
  4. The real run completes with exit value 0. Read the exit value with your usual job tooling.

What to watch afterwards

  • Log the full rsync output and the exit value for every run, since the error text alone does not say which cause applies.
  • After an operating system rebuild on either side, test rsync --version over ssh before the first job.
  • Watch free space on destinations.
  • Keep job output separate from the remote shell's startup output.

Risks and limits

  • These commands have not been run or lab-tested.
  • Message wording is from the rsync source on its master branch and the FAQ. Older rsync versions word it a little differently; the FAQ examples have a byte count of 24 and no bracketed field.
  • A count above zero means the remote side sent something before the connection closed, so the causes of disk, network and shell output on the issues and debugging page apply, not only the path tests.
  • Exit values other than 12, such as 23 and 24, are separate faults. See "rsync error code 23 and 24 in backup jobs: partial transfer, vanished files and when to treat them as failure".

Sources

  • rsync(1) manual page — rsync project, 4 Nov 2026 (version 3.5.2), accessed 20 November 2026
  • rsync FAQ — rsync project, no date shown, accessed 20 November 2026
  • rsync: current issues and debugging — rsync project, no date shown, accessed 20 November 2026
  • rsync source: io.c — rsync project, master branch, no date shown, accessed 20 November 2026
  • ssh(1) — OpenBSD manual page, OpenBSD-current, November 2, 2026, accessed 20 November 2026
  • ssh_config(5) — OpenBSD manual page, OpenBSD-current, October 30, 2026, accessed 20 November 2026
  • sshd_config(5) — OpenBSD manual page, OpenBSD-current, October 30, 2026, accessed 20 November 2026
  • df(1) — GNU coreutils 9.11 manual page, April 2026, accessed 20 November 2026
  • cp(1) — GNU coreutils 9.11 manual page, April 2026, accessed 20 November 2026