Proxmox Backup Failed: Fixing Common vzdump Errors

Why Proxmox Backups Fail

Backups are the safety net of your entire Proxmox infrastructure, and a failed backup you do not notice is worse than no backup at all. Proxmox uses vzdump under the hood for all backup operations, and its error messages, while sometimes cryptic, usually point directly to the root cause once you know what to look for.

This guide covers the most common vzdump failures and provides concrete fixes for each one.

Error: Storage Full

The most frequent backup failure. Your backup storage has run out of space, either because backups accumulated without rotation or a single backup grew larger than expected.

# Check storage usage
df -h /mnt/backup-storage
pvesm status

# See how much space existing backups consume
du -sh /mnt/backup-storage/dump/*

# Fix 1: Remove old backups manually
ls -lt /mnt/backup-storage/dump/*.vma.zst
rm /mnt/backup-storage/dump/vzdump-qemu-100-2026_01_01-00_00_00.vma.zst

# Fix 2: Configure backup retention to auto-prune
# In Datacenter > Storage > your backup storage:
# Set keep-last, keep-daily, keep-weekly, keep-monthly

# CLI equivalent: edit storage config
pvesm set local-backup --prune-backups keep-last=3,keep-daily=7,keep-weekly=4

# Fix 3: Enable compression to reduce backup size
# In backup job settings, use zstd compression:
# vzdump 100 --compress zstd --storage local-backup

Error: Lock - Another Backup Is Running

This error occurs when a VM is already locked by another vzdump process, a snapshot, or a migration.

# Check if the VM has an active lock
qm config 100 | grep lock

# Check for running vzdump processes
ps aux | grep vzdump

# If a previous backup crashed and left a stale lock:
qm unlock 100

# For containers:
pct unlock 200

# Check the vzdump task log for the stuck backup
cat /var/log/vzdump/*.log

# If a backup process is truly stuck, kill it
kill $(pgrep -f "vzdump.*100")
qm unlock 100

Never unlock a VM while an active backup or migration is genuinely running. Always verify the process is actually stale before removing the lock.

Error: Backup Timeout

Large VMs or slow storage can cause backups to exceed the configured timeout. This is especially common with snapshot-mode backups on busy VMs.

# Default vzdump timeout is typically unlimited, but
# individual operations within the backup can time out

# Guest agent fsfreeze timeout (default 60 seconds)
# If fsfreeze times out, backup continues without consistent state
# Increase timeout in /etc/vzdump.conf:
# freeze-fs-on-backup: 1

# For very large VMs, check if I/O bandwidth is the bottleneck
iostat -x 5 3

# Speed up backups with faster compression
# In /etc/vzdump.conf:
pigz: 4          # Use 4 threads for gzip compression
# Or use zstd which is faster:
# compress: zstd

# Consider scheduling large VM backups during low-usage hours
# Edit backup job schedule in Datacenter > Backup

Error: IO Error During Backup

IO errors during backup usually indicate hardware problems with either the source disk or the backup storage destination.

# Check for disk errors in system logs
dmesg | grep -i "error\|fault\|bad"
journalctl -k | grep -i "i/o error"

# Check SMART status of local drives
smartctl -a /dev/sda

# Check ZFS pool health if using ZFS
zpool status

# For NFS-based backup storage, check mount health
mount | grep nfs
nfsstat -c

# Test backup storage write speed
dd if=/dev/zero of=/mnt/backup-storage/test.bin bs=1M count=1024 oflag=direct
rm /mnt/backup-storage/test.bin

# If using a network storage target, check connectivity
ping -c 10 192.168.1.100

Error: Permission Denied

Permission errors occur when the backup process cannot read VM disks or write to the backup destination.

# Check backup storage permissions
ls -la /mnt/backup-storage/dump/

# Proxmox backups run as root, so this usually means:
# - NFS export with root_squash enabled
# - Storage mounted with wrong permissions
# - SELinux/AppArmor blocking access

# Fix NFS root_squash on the NFS server:
# In /etc/exports:
# /mnt/data/proxmox 192.168.1.0/24(rw,sync,no_subtree_check,no_root_squash)
# Then: exportfs -ra

# Fix local directory permissions
chown -R root:root /mnt/backup-storage/dump/
chmod 755 /mnt/backup-storage/dump/

# Check if storage is mounted read-only
mount | grep backup
# If read-only, remount:
mount -o remount,rw /mnt/backup-storage

Cleaning Up Partial Backups

When a backup fails partway through, it may leave behind partial files that consume disk space without being usable.

# Find partial or temporary backup files
ls -la /mnt/backup-storage/dump/tmp/
ls -la /mnt/backup-storage/dump/*.dat

# Identify incomplete backups (no corresponding .notes file)
ls /mnt/backup-storage/dump/*.vma* | head -20

# Check vzdump log for the failed job to identify partial files
cat /var/log/vzdump/vzdump-100.log

# Remove confirmed partial backups
rm /mnt/backup-storage/dump/vzdump-qemu-100-2026_03_15-*.vma.zst.tmp

# To prevent partial file buildup, configure notifications
# so you catch failures early. Tools like ProxmoxR can
# consolidate backup status across multiple nodes.

Verifying Backup Integrity

A backup that completed without errors may still be corrupt. Regularly verify your backups can be restored.

# List backups for a specific VM
vzdump --list 100

# Verify a backup file's integrity (basic check)
vma verify /mnt/backup-storage/dump/vzdump-qemu-100-2026_03_16-00_00_00.vma.zst

# For Proxmox Backup Server backups
proxmox-backup-client verify --repository user@pbs:datastore

# Test restore to a temporary VM (best verification)
qmrestore /mnt/backup-storage/dump/vzdump-qemu-100-2026_03_16.vma.zst 999
# Verify VM 999 boots correctly, then remove it
qm destroy 999

Backup Troubleshooting Checklist

• Check storage space on the backup destination before investigating other causes
• Look at /var/log/vzdump/ logs for detailed error messages
• Verify no stale locks exist on the VM with qm config
• Test backup storage connectivity and write performance
• Configure backup retention to prevent storage from filling up
• Set up email or webhook notifications for backup job failures
• Periodically test restoring from backups to confirm they work

Reliable backups require active monitoring, not just scheduling a job and hoping for the best. Address failures promptly and test restores regularly to ensure your safety net actually works when you need it.