The rsync utility is the premier tool for local and remote file synchronisation, backups, and server migrations in Linux. However, completing a large transfer only to be greeted by the exit warning: ‘rsync error: some files/attrs were not transferred (see previous errors) (code 23) at main.c’ indicates that while many files were transferred successfully, specific files, directory attributes, or symbolic links encountered fatal errors. Understanding how to extract the exact offending file paths and resolve underlying file system constraints ensures complete data integrity for your backups.
What Causes rsync Exit Code 23?
Exit code 23 is a partial transfer error generated when rsync encounters an operating system restriction during directory traversal. Common causes include:
- Permission Denied on Source or Target: The executing user account lacks read permissions on sensitive files (such as
/etc/shadowor user home directories) or lacks write permissions on the destination folder. - Filesystem Incompatibilities and Attribute Failures: Transferring files between different filesystem types (e.g., from Linux
ext4to WindowsNTFSorFAT32) where target drives cannot support Linux POSIX file ownership (chown), group permissions, or extended attributes (xattrs). - Dangling or Broken Symbolic Links: Symbolic links pointing to non-existent target files when rsync is configured to copy link targets rather than raw symlinks.
- Immutable Filesystem Attributes (chattr): Files flagged with the immutable (
+i) attribute that cannot be modified or replaced even by the root user. - Files Vanishing During Active Transfer: Log files, lock files, or temporary swap items being deleted by active server processes while rsync is reading the directory tree.
Step 1: Identify Offending Files with Verbose Logging
Rsync error code 23 is generic; the actual culprit is printed earlier in standard error output. Adding logging flags isolates the specific failure.
- Re-run your rsync command with the verbose (
-v), itemize-changes (-i), and log-file options:rsync -avz --itemize-changes --log-file=/tmp/rsync_error.log /source/dir/ /destination/dir/ - Once the transfer finishes with code 23, filter the log file for permission or transfer failures:
grep -iE "permission denied|failed|vanished" /tmp/rsync_error.log - Note the exact filenames causing the transfer failure.
Step 2: Run rsync with Sudo or Correct User Ownership
If the error displays Permission denied (13), rsync is attempting to access files owned by root or another user account.
- If transferring local system files or user directories, execute the command with superuser privileges:
sudo rsync -avh /source/dir/ /destination/dir/ - When synchronising over SSH to a remote server, specify a remote user with root privileges, or configure
--rsync-path:rsync -avh -e ssh --rsync-path="sudo rsync" /local/dir/ user@remote-host:/remote/dir/ - This ensures the remote daemon has superuser privileges to write files and adjust ownership on the target machine.
Step 3: Modify Attribute Flags for Non-POSIX Destinations (NTFS / FAT32)
When synchronising files to an external USB drive formatted as FAT32, exFAT, or NTFS, the destination drive cannot accept Linux ownership (chown) or file permission (chmod) attributes.
- Replace the full archive flag (
-a) with specific flags that omit ownership and group attributes:rsync -rltDv /source/dir/ /media/usb-drive/destination/ - Alternatively, use the
--no-perms --no-owner --no-groupflags:rsync -av --no-perms --no-owner --no-group /source/dir/ /media/usb-drive/destination/ - This allows files and timestamps to copy smoothly without rsync halting over unsupported attribute operations.
Step 4: Handle Broken Symbolic Links
If your source directory contains dangling symbolic links, copying them as file targets causes transfer failures.
- To copy symbolic links as symlinks without attempting to resolve their targets, ensure the
-lflag is used (included in-a):rsync -av --copy-links /source/ /destination/ - If you want rsync to skip broken symlinks completely, use the
--safe-linksflag:rsync -av --safe-links /source/ /destination/ - This ignores links pointing outside the source tree or pointing to non-existent paths.
Step 5: Ignore Vanishing Files on Active Production Servers
On active web or database servers, transient files (such as .pid files, temporary caches, or rotating logs) may be removed while rsync is reading directories.
- Add the
--ignore-missing-argsflag to prevent rsync from throwing code 23 when a source argument vanishes:rsync -av --ignore-missing-args /source/ /destination/ - If files inside directories are actively disappearing, install a wrapper or combine with exclude patterns:
rsync -av --exclude="*.tmp" --exclude="*.sock" --exclude="*.log" /source/ /destination/
Identifying the root cause through error logs and tuning attribute flags ensures your rsync backups finish cleanly with exit code 0 every time.