When a backup fails, you need clear steps, not guesses. This guide shows you how to troubleshoot Proxmox Backup Server (PBS) from the first check to the final fix. It covers:
You need root or sudo access to the PBS host, and shell access to one Proxmox VE (PVE) node that sends backups. If you are still building your server, you can read the Proxmox Backup Server setup tutorial.
Check your PBS version. S3 fixes in this guide depend on it:
Follow these steps in order, and you can troubleshoot Proxmox Backup Server without risky changes. Two rules you must consider before you change anything:
Always start with the following checks. They tell you where to look next.
Number 1: Check the services with the following command. Both services must be active (running). The proxy handles the web UI and the API on port 8007:
Number 2: Read the recent logs with the following commands:
Number 3: Find the failed task and read its log with the commands below:
Also, task logs are saved in /var/log/proxmox-backup/tasks. In the web UI, open Administration > Tasks. On the PVE side, the backup log is in the node's task history.
Number 4: Run the datastore health checks by running the commands below:
If your datastore is on ZFS, also run the following command:
You must look for disk usage above 90%, no free inodes, SMART warnings, and disk or file system errors in dmesg.
Number 5: Check your scheduled jobs with the following commands:
Many problems come from jobs that run at the same time. Write the schedules down and look for overlap.
Where to Start: Match Your Symptom to the Fix
You can easily find the symptom you see in the table below. Then go to the section that fixes it. This saves time during an incident.
When you troubleshoot Proxmox Backup Server backup failures, split the problem into two questions:
First, test the connection from the PVE node with the commands below:
Port 8007 must be open. The time must be correct on both sides because login tickets depend on it.
Then, test a real login with the backup client. Use your API token as the user and its secret as the password:
If PBS uses a self-signed certificate, you must add PBS_FINGERPRINT (check the section below).
A failed backup does not always mean your data is damaged. Start by checking the error message in the task log. Then, use the table below to find the possible cause, check it, and follow the fix. This helps you avoid changing settings that are not related to the problem.
PVE checks the PBS certificate fingerprint on every connection. If the certificate changes, PVE stops the backup and shows a fingerprint error. This usually happens after a certificate renewal or a PBS reinstall.
To fix it, you must get the new fingerprint from PBS and add it to the PVE storage:
PBS removes old unfinished backups when you prune. It keeps the last failed backup only if it is newer than the last one. So a failed snapshot that stays visible is usually the newest one, and it is normal.
PBS 4.1 came with kernel 6.17. Some users saw backups become very slow or get stuck. If this happens to you, the release notes say to switch back to the older 6.14 kernel:
PBS 4.2 uses kernel 7.0 as the new default, so upgrade first if you can.
A permission error means PBS knows who you are, but it will not let you do the action. This can happen for two reasons. Either the user or token does not have the right access rules in PBS, or the Linux folder rights on the datastore are wrong. You must check both, one by one.
New users and API tokens have no permissions at all. Also, a token has its own rules, and it can never do more than its user.
First, check what a token can really do with the commands below:
Then, let your backup token create backups with the command below:
Keep these rules in mind:
Datastore.Backup lets a user create backups and read or verify only the groups it owns.Datastore.Prune also needs ownership of the group.DatastorePowerUser can back up, restore, and prune owned backups.This is common after you switch from a user to a token, or from a token to a user. To change it, run:
Also, you can do this in the web UI from the datastore Content tab.
PBS runs as the backup user. The datastore folder must belong to it:
If the owner is wrong, fix it while no backup is running:
Also, make sure the path in /etc/proxmox-backup/datastore.cfg matches the real mount point. If you change the path or the owner, restart the proxy when no tasks are running:
The ext4, xfs, and zfs are the supported file systems for a datastore. If a mount point is empty after a reboot, check that the disk was mounted before PBS started.
PBS uses locks so two jobs do not change the same data at once. A lock error means another task still holds it, or the server is very busy. Lock problems are easy to troubleshoot in Proxmox Backup Server once you know which task holds the lock.
A lock error means another task is using the datastore. First, you must find out which task it is. The commands below show all running tasks and the lock messages in the logs.:
Wait for the running task to end, or stop it from Administration > Tasks in the web UI.
Backup, prune, garbage collection, verify, and sync jobs should not all start at the same time. A simple plan includes:
An error such as Unable to acquire lock ".../tasks/.active.lock" appears when many backups start in the same second. PBS already waits up to 15 seconds for this lock. Spread out the start times of your backup jobs instead of starting every node at midnight.
A removable datastore that fails to unmount can stay in unmounting mode, which blocks all IO. Reset it like this:
The first command blocks all IO. The second one clears the mode.
Newer releases fixed several lock problems. For example, PBS 4.1 fixed a case where a backup did not drop its lock in time, so the next backup failed. Also, it fixed a locking issue where a backup was not given priority over garbage collection during a server reload.
Read the release notes first. Then, upgrade when no backups are running.
Do not delete lock files manually while PBS is running. If a lock still stays after you stop all tasks, save the journalctl output and check it for the cause.
Many people get confused here. When you troubleshoot Proxmox Backup Server disk usage, first ask: did GC run after the prune? Prune does not free disk space. It only removes the snapshot records. The data stays on disk until garbage collection (GC) removes it.
GC works in two phases. In phase 1, it marks every chunk that a snapshot still uses. It does this by updating the chunk's access time (atime). In phase 2, it deletes chunks that were not marked and are older than a cutoff time. The cutoff is 24 hours and 5 minutes before GC started, or the start of the oldest running backup, whichever is earlier.
Chunks newer than the cutoff are not deleted yet. The GC log shows them as Pending removals. This is not an error. PBS waits because most file systems use relatime, which updates atime only about once a day. So the real cycle is:
Use the commands below to test your prune rules, run GC, and check its status. First, run the prune command with --dry-run. It shows what would be removed without deleting anything:
Manage prune jobs and GC with the following commands:
Then, set a weekly GC schedule with the command below:
GC can fail or not free space for a few simple reasons. The table below shows the most common problems and how to fix each one.
Do not try to make the GC wait time shorter to get space back faster. The wait time protects running backups from losing data.
Verification reads every chunk and checks its checksum. To troubleshoot Proxmox Backup Server verify errors, you must find out if the cause is the disk, the data, or the S3 provider. A failed verify means PBS found a chunk that is missing or does not match.
A verify job reads your backup data and checks that it is not damaged. You can start one manually at any time. Use the command below to check the whole datastore, or use the web UI to check one snapshot:
The thread defaults are 1 reader and 4 verify threads, and you can use values from 1 to 32. To check one snapshot, open the datastore Content tab and click the verify icon on that snapshot.
A failed verify means PBS found a chunk that is missing or damaged. Follow the steps below to find the cause. Most of the time, the problem is the disk.
smart-attributes, zpool status -v, dmesg).resync-corrupt option. It re-syncs snapshots that failed the last verify, so run a verify job first.Once a chunk fails on disk, it will not fix itself. You must fix the hardware cause first, or the same errors will return.
Check all your backups again at least once a month. A simple plan is two jobs, including a daily job for new backups, and a weekly or monthly job that checks everything. Also, you can verify new backups right after they finish by turning on the datastore verify-new option.
Verify is heavy on disk and CPU. You can change the thread numbers and the chunk order. For fast NVMe, chunk-order=none can be faster than the default inode order.
First look at your current tuning, because the new value replaces the old one:
A sync job copies backups from one PBS server to another. When it fails, the cause is usually the network, the certificate, or missing rights. Run the job manually, read the log, and then use the checklist below.
A pull job needs two rights:
Remote.Read on /remote/{remote}/{remote-store}Datastore.Backup or higher on /datastore/{store}PBS 4.2 can sync several groups at once. The default is 1 worker, and the maximum is 32:
More workers use more memory and more connections on both servers. Start low and raise the number slowly.
A sync job can use all of your network speed and slow down other work. You can set a speed limit to stop this. Use rate-in for pull jobs and rate-out for push jobs:
Push jobs in PBS 4.2 can encrypt snapshots before they leave your server. Snapshots that are only partly encrypted are skipped. If a job skips snapshots, check the encryption key setup and the encrypted-only flag.
Slow backups can come from the CPU, the network, or the disk. Test each part in the order below. This helps you find the slow part quickly, without changing settings you do not need to change.
Run the command below to check TLS speed, hashing, compression, and encryption speed:
Low TLS speed points to the network or a weak CPU.
At this point, you must check for the wrong MTU or a bad switch port. Run the command below:
In PBS 4.1, switching back to the default MTU of 1500 helped fix slow or stuck backups in some cases.
Next, check whether the datastore disk is slowing down your backups. Use the commands below to see how busy the disk is and how long read and write requests take:
If %util stays near 100% and wait times are high, the datastore disk is slowing down your backups. PBS needs fast access to small files across the disk. Use enterprise SSDs, or add a metadata cache, such as a mirrored ZFS special device, if you use HDDs.
Check whether other jobs are running during your backups. GC, verify, and sync jobs also use disk and network resources. You must move them to a different time so they do not slow down your backups.
Check your traffic limits and datastore settings. A speed limit or a storage setting may be slowing down your backups. Review the options below before making changes.
sync-level is filesystem. The file level runs fsync on every chunk and is slow on slow storage.chunk-order at inode for HDDs. Try none only on very fast NVMe.S3 backups depend on your storage provider, network, and local cache. A problem with any of these can cause errors or slow backups. This section covers common S3 issues in PBS 4.2, cache space, and storage costs.
All data goes to the S3 bucket, but PBS still needs a persistent local cache. The cache keeps metadata and recent chunks, so PBS does not call S3 for every action. Important facts:
To troubleshoot Proxmox Backup Server S3 datastores, you must test the endpoint before you test the datastore.
list-buckets is the fastest test. If it fails, no datastore task will work.
You can find your error in the table below. Check the possible cause, then follow the steps to fix it.
For AWS, use the endpoint {{bucket}}.s3.{{region}}.amazonaws.com and set the region in its own field. The region is part of the request signature.
You can set a provider quirk from the CLI or from Configuration > Remotes > S3 Endpoints > Edit:
If your S3 provider blocks downloads, a verify job may mark snapshots as failed even when the stored data is not damaged. For example, the provider may return HTTP 403 when you reach a daily download limit. To fix this:
If a verify job skips snapshots already checked, it may also skip those marked with errors. This means the error status may stay until you check them again. Check your version’s release notes for a fix.
If you changed objects in the bucket manually, lost the cache, or cleaned up stray objects, you must refresh the local cache from S3:
PBS 4.2 fixed two refresh bugs, including a crash on every refresh that started in PBS 4.1, and empty namespaces that were skipped.
The cache is a normal folder on your local disk, so it can fill that disk. A common mistake is to place it on the root disk, which then runs out of space. Check it with:
In PBS 4.2, the web UI shows this number as Local Cache Usage. Follow these rules:
Example of a ZFS cache with a quota:
Known issue in PBS 4.0: cache space may stay used after a restart, reboot, or maintenance mode. If this happens, check the latest release notes and update PBS.
If your cache disk is slow or nearly full, you must move the cache to a faster disk with more space. Remember to stop all running tasks before you start.
S3 providers may charge for storage, requests, and downloads. You must check your usage to avoid unexpected costs. You can set notification limits and a schedule that resets the counters, for example once a month:
GC and verify make many S3 requests, so check your usage after they run. PBS 4.1 adds speed limits per S3 endpoint, and PBS 4.2 adds HTTP proxy support for S3 traffic.
High RAM use in PBS is usually normal. Before you troubleshoot Proxmox Backup Server memory use, remember that Linux uses spare RAM on purpose. Find out which part uses it before you act:
Read the available column in free -h, not the free column. Linux uses spare RAM for file cache, and gives it back when programs need it. Common causes include:
ZFS uses RAM to cache data. If it uses too much, you must set a limit to leave enough memory for PBS and other tasks. To set a limit of 8 GiB, you can use:
GC keeps a cache of chunks that it has already marked. The default is 1048576 slots, and the maximum is 8388608. Higher numbers can shorten GC but use more memory. A value of 0 turns the cache off.
Check your current tuning first, and include the other options, because the new value replaces the old one.
It is recommended to consider at least 4 GiB of RAM for the OS, file cache, and PBS services, plus at least 1 GiB for each TiB of storage. Add more if you use ZFS, run many jobs at once, or use sync workers. For S3 datastores, plan RAM for the system plus fast local disk for the cache.
If your jobs keep fighting for RAM and disk speed, you can move backups to a separate machine. A dedicated server for backup infrastructure with enough NVMe for the S3 cache and enough RAM gives you steady backup and restore speed, and your production hosts stay free for production work.
Always start with the task logs, then check storage, permissions, and running jobs. Keep backups, GC, verify, and sync jobs on separate schedules. For S3, watch cache space and costs. Also, test your restores regularly to make sure your backups are ready when you need them.
We hope you enjoy this guide to troubleshoot Proxmox Backup Server. For more detailed information, you can check the PBS Maintenance Tasks Docs.