cPanel/WHM Incremental Backup Not Working? Fix Rsync Prune Errors and Restore Failures

cPanel/WHM incremental backups save disk space and reduce backup windows — but when they break, the errors are cryptic. A frozen rsync process, an "unable to prune transport" alert in WHM, or a restore that silently fails can leave your clients unprotected for days. This guide walks through every failure mode sysadmins encounter with cPanel incremental backups and gives you the exact commands to diagnose and fix them fast.

How cPanel Incremental Backups Work (and Why They Fail)

cPanel's incremental backup system uses rsync to copy only changed files to the backup destination. Each incremental snapshot is stored as a directory tree with hard links to unchanged files from the previous backup, keeping disk usage low while giving you multiple restore points.

The system runs under /usr/local/cpanel/bin/cpbackup and logs to /usr/local/cpanel/logs/cpbackup/. When the rsync transport fails to prune (delete) old snapshots within the 300-second timeout, WHM logs the error and marks the destination unhealthy — blocking future backups entirely until you clear the state.

Diagnosing the Problem: Read the Backup Logs First

Before touching any configuration, read the logs:

# Most recent backup log
ls -lt /usr/local/cpanel/logs/cpbackup/ | head -5
tail -200 /usr/local/cpanel/logs/cpbackup/$(ls -t /usr/local/cpanel/logs/cpbackup/ | head -1)

# Check for rsync prune errors specifically
grep -i "prune\|transport\|unable\|timeout\|failed" /usr/local/cpanel/logs/cpbackup/$(ls -t /usr/local/cpanel/logs/cpbackup/ | head -1)

Common error strings to look for:

• Unable to prune transport — rsync could not delete expired snapshots
• Connection to remote server stalled — network timeout mid-transfer
• rsync: [sender] write error: Broken pipe — remote host dropped the connection
• cannot delete non-empty directory — permission mismatch on backup destination
• Backup process timed out — the default 7200-second backup timeout was hit

Fix 1: Increase the Rsync Transport Timeout

The most common cause of prune failures is the 300-second per-transport timeout expiring before rsync finishes deleting a large snapshot directory. Fix it in WHM:

1. Log in to WHM → Backup → Backup Configuration

2. Scroll to Additional Destinations → click your rsync destination → Edit

3. Find the Timeout field and increase from 300 to 900 or 1800 seconds

4. Click Save and Validate — WHM will test connectivity before saving

Also increase the global backup timeout if the backup itself is timing out:

• WHM → Backup → Backup Configuration → Timeout field → raise from 7200 to 14400 seconds

Fix 2: Manually Clear the Stuck Prune Queue

If WHM shows the destination as "Failed" or "Unable to prune", the old snapshot directory must be deleted manually before new backups can run.

1. Find the stuck snapshot on the backup destination (SSH into the rsync target or use a local path):

ls -lt /backup/cpanel_incremental/ | head -10
# Look for directories older than your retention window

2. Remove the expired snapshot directory:

# Replace the path and date with the actual snapshot
rm -rf /backup/cpanel_incremental/2026-05-20

3. Reset the destination state in WHM:

/usr/local/cpanel/bin/backup_transport_queue_manager --reset-failed

4. Run a manual backup to verify:

/usr/local/cpanel/bin/cpbackup --force daily &

Fix 3: Resolve File Permission Errors

CMS installations like Drupal set strict directory permissions (e.g., 0555) that block rsync from writing hard links during an incremental backup. The backup log will show errors like rsync: recv_generator: mkdir failed or cannot delete non-empty directory.

Check and fix permissions for the affected account:

# Find directories that block rsync (mode 555 or 444)
find /home/USERNAME -type d -perm /222 -prune -o -type d -not -perm -222 -print | head -20

# Fix recursively (use with care — verify with the site owner first)
find /home/USERNAME/public_html -type d -exec chmod u+w {} \;
find /home/USERNAME/public_html -type f -exec chmod u+w {} \;

For Drupal specifically, the sites/default/files directory is typically set to 0555 by Drupal's own security hardening. Add a pre-backup hook or switch that account to compressed backups in WHM's per-account backup settings.

Switch a single account to compressed backup:

1. WHM → Backup → Configure Backup → Accounts tab → find the user → set Backup Type Override to Compressed

Fix 4: Fix "Connection to Remote Server Stalled" Errors

This error occurs when the rsync SSH tunnel stalls — usually due to a flaky network path or the remote server dropping idle connections.

Add SSH keepalive options to the rsync destination config:

# Edit or create /root/.ssh/config (or the backup user's .ssh/config)
cat >> /root/.ssh/config << 'EOF'
Host backup-destination-hostname
    ServerAliveInterval 60
    ServerAliveCountMax 5
    TCPKeepAlive yes
EOF

Check the remote SSH server's idle timeout (/etc/ssh/sshd_config on the destination):

ClientAliveInterval 120
ClientAliveCountMax 5

Reload sshd on the destination after editing: systemctl reload sshd

Fix 5: Diagnose and Recover a Failed Restore

A restore that completes without output — or shows a partial account — usually fails due to a corrupted .tar.gz file, a mis-named backup archive, or a restricted restore security flag blocking a component.

Verify the backup archive before restoring:

# Test integrity of a cpmove/full backup archive
tar -tzf /home/backup-2026-05-28_14-30-00_username.tar.gz > /dev/null && echo "OK" || echo "CORRUPT"

# For incremental restore, verify the snapshot directory structure
ls -la /backup/cpanel_incremental/2026-05-28/username/

Restore via CLI instead of WHM GUI (more verbose output):

/usr/local/bin/whmapi1 restore_account_backup backup_file=/home/backup-2026-05-28_14-30-00_username.tar.gz

Check the restore log for specific component failures:

tail -f /var/cpanel/restore.log

If the restore log shows Restricted restore blocked: [component], switch to unrestricted restore only if you trust the backup source:

/usr/local/bin/whmapi1 restore_account_backup backup_file=/path/to/file restricted_restore=0

Fix 6: Switch to Compressed Backups When Rsync Is Unsuitable

Rsync incremental backups are efficient but have hard constraints: they cannot back up to remote destinations that require compressed files, and they struggle with accounts that have millions of tiny files (like high-traffic Magento installs with var/cache). If repeated prune failures are burning your time, switching to compressed backups may be the right long-term answer.

Navigate to WHM → Backup → Backup Configuration → Backup Type → set to Compressed. Increase retention settings to compensate for the higher disk usage. Compressed backups write single .tar.gz files per account — easier to verify, move, and restore.

Preventing Future Incremental Backup Failures

• Monitor destination health weekly: WHM → Backup → Backup Configuration → validate each destination
• Set a disk-space guard: WHM → Backup → Backup Configuration → Minimum Free Disk Space → keep at 10%+
• Alert on backup failures: WHM → Contact Manager → enable Backup Failed notifications
• Test restores quarterly: spin up a staging account and restore a real backup — silent failures are common
• Limit incremental snapshots: keep no more than 7 daily + 2 weekly to prevent prune timeouts on slow destinations

Incremental backup failures in cPanel/WHM almost always come down to three causes: timeout limits set too low, permissions that block rsync's hard-link mechanism, or snapshot directories that grew too large to prune within the default window. Armed with the log paths, the timeout settings, and the manual prune commands above, you can diagnose and fix any of these in under 30 minutes. For managed cPanel server support and proactive backup monitoring, CloudHouse Technologies' server management service keeps your backup pipeline healthy around the clock.