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

NetLeverage
NetLeverage

rsync error code 23 and 24 in backup jobs: partial transfer, vanished files and when to treat them as failure

Technical article
Backup & Recovery

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.

rsync exit status 23 is documented as "Partial transfer due to error": something in the run failed, so the backup does not hold everything you asked for. Exit status 24 is "Partial transfer due to vanished source files": a file listed at the start was gone by the time rsync reached it. The first must be treated as a failed or incomplete backup until you have read which files were affected. The second is often harmless on a busy server, but only after you have read the output, because one real-world report shows 24 appearing alongside a real error.

What the error means

The rsync manual page in Debian 13 (trixie), which describes rsync 3.4.1, lists the exit values. The ones relevant here are:

  • 11: "Error in file I/O"
  • 13: "Errors with program diagnostics"
  • 23: "Partial transfer due to error"
  • 24: "Partial transfer due to vanished source files"
  • 25: the --max-delete limit stopped deletions (paraphrased)

The manual does not say which errors cause 23. It is a summary code; the individual failures are printed earlier in the output, on standard error. A "partial" transfer means most of the destination can look populated and healthy, which is exactly why it is dangerous.

Two details from the community show what hides behind these numbers.

Code 24 can sit beside a real error. A user posted to the rsync mailing list in January 2013 (Error #24 masks error #23?, Ken Preslan, 22 January 2013) with output that contained both rsync: rsync_xal_set: lsetxattr("/path/to/file","xattrname") failed: Argument list too long (7) and file has vanished: "/path/to/other/file". rsync returned 24 although the first message is an extended-attribute failure. The post asks whether the last error is the one reported; the manual does not say which code wins when both occur, so do not assume an order. The practical lesson stands without it: never judge a run by the exit code alone.

Missing files in a file list return 23. A contributor on the same list in December 2007 (what is the right exit code for some vanished files?, Matt McCutchen) said that for entries given with --files-from that no longer exist, "Code 23 is correct according to the current interpretation of --files-from", because the user wants every listed file copied. He was answering a direct question about this, and the statement describes older behaviour; it is not current documentation.

Likely causes

Cause What you see How to confirm
Source files deleted or rotated while the job ran (logs, temp files, mail spools) Exit 24; file has vanished: "<path>" lines The paths named are transient and the same kinds of files each night
A file rsync cannot read or write (the message names the reason, such as a permission or I/O error) Exit 23; error lines naming paths Read the stderr lines for the affected paths
Destination cannot store ACLs or extended attributes that -A or -X ask for Exit 23; xattr or ACL error lines such as the lsetxattr example above Run with the options you use and read the messages; check the destination file system
A path listed with --files-from or as a source argument no longer exists Exit 23 (list entries, per the 2007 post) or an initial error on a missing source Compare the list with the source
Errors reading or writing (disk full, I/O errors, remote disconnects) Exit 23 or 11 with matching messages Messages near the failure; system logs on both sides
Both vanished files and a real error in one run Exit 24 or 23; the exit code understates the problem Read all of stderr, not just the exit code

Prove the cause before changing anything

None of these steps changes the data. The commands use options documented in the manual page and have not been run.

  1. Capture the messages. If your job discards stderr, run it again with the output saved. The manual's option summary lists --log-file=FILE, and --verbose "increases the amount of information you are given during the transfer". Redirecting standard error to a file in your own script works too.

  2. Find the files named in the messages. Look for lines before the final "partial transfer" summary, not the summary itself. Separate "vanished" lines from permission, xattr, ACL and I/O errors.

  3. See what a rerun would still change, without changing it. The manual describes --dry-run (-n) as "a trial run that doesn't make any changes (and produces mostly the same output as a real run)", and --itemize-changes (-i) as a list of changes made to each file. For example:

    rsync -a -n -i <source>/ <destination>/
    

    Files still listed after a completed run are not up to date on the destination. The manual notes that -a does not include -A (ACLs), -X (extended attributes) or -H (hard links), so add the ones your job uses.

  4. Check statistics. --stats prints "a verbose set of statistics on the file transfer", useful for comparing file counts between runs.

  5. Check which files are the vanished ones. Decide whether each is a file you intended to back up. A temporary file that disappeared is not a loss; a database file or a user document that disappeared is.

Example (illustrative). A nightly job on WEB01 ends with exit 24 most nights. The saved output lists a few session files under a cache directory as vanished. The same files never appear in the backup on any night, and no other errors are in the output. That pattern is benign. If one night's output instead lists lsetxattr failures on a data share, the exit code is not the whole story and the run is incomplete.

Fix

Real errors (exit 23).

  • Fix permissions or run the job with the access it needs (for example as a user that can read all source paths).
  • If -A or -X fail on the destination, the destination file system or mount does not support what you ask. Either use a destination that does, or drop the option and accept that ACLs or xattrs are not backed up. Dropping them silently changes what the backup is worth, so record the decision.
  • Fix disk-full and I/O faults on the destination, then rerun and confirm a clean exit.

Files that vanish (exit 24).

  • Exclude the transient paths from the job so the noise goes away and a real vanished file stands out.
  • For files that matter (databases, mail stores), do not rely on copying them while they change. Take a snapshot first (an LVM snapshot, for example, created as in the lvcreate manual page) and run rsync from the mounted snapshot, so the source cannot change during the run.
  • --ignore-missing-args is not the answer for this. The manual says it suppresses the error for source files that cannot be found initially and "does not try to transfer the file"; it concerns files missing at the start, not files that disappear during the run.

Wrapper scripts. A wrapper that treats exit 23 as success hides missing data, because 23 includes permission and attribute failures. If your wrapper must tolerate some vanished files, make the rule narrow:

  • Accept 0 as success.
  • Accept 24 only after confirming from the saved output that every message is a vanished-file message for an expected path, and that there are no other error lines.
  • Treat 23 and every other non-zero code as a failed backup and alert on it.

Deletion. If you use --delete, the manual says --ignore-errors "tells --delete to go ahead and delete files even when there are I/O errors". Do not add it to make a job pass.

Confirm the fix

  • The job exits 0, or exits 24 only with expected transient paths and no other messages.
  • A dry run (-n -i) after the real run lists nothing for the paths that matter.
  • Spot-check the ACLs and extended attributes on the destination for files that needed them, if your job uses -A or -X.
  • Restore a sample, including permission-sensitive files, to a scratch location and compare it with the source. A completed job is not proof of a usable backup.

What to watch afterwards

  • Alert on any exit status other than 0 and, if you accept it, a narrowly validated 24.
  • Count vanished-file lines and error lines per run; a jump in either is the recurrence signal.
  • Review the exclude list after application changes that move temporary or spool files.
  • Keep the saved stderr for at least as long as you keep the backups it describes.

Risks and limits

  • These commands have not been run or lab-tested. They come from the rsync manual page and mailing-list posts.
  • The manual page quoted is the Debian 13 package of rsync 3.4.1; exit-code text and options may differ on older or newer versions.
  • The manual lists the exit values but does not explain which failures cause 23, or how 23 and 24 are chosen when both occur; the mailing-list posts are individual reports, not documentation.
  • Raising or lowering what counts as a failure is a policy decision. The rules above are a conservative reading of the documented meanings.
  • Mailing-list posts are from 2007 and 2013 and describe older releases.

Sources