Troubleshooting

Common Proxmox Backup Server errors, decoded.

The errors below are quoted the way PBS and vzdump actually print them, because that's how you searched for them. Each entry: what it means, what to do, and what it's trying to warn you about.

Updated July 2026 • For quick triage steps, see the shorter troubleshooting checklist.

certificate fingerprint does not match expected fingerprint

connect to 'pbs.example.com:8007' failed:
certificate fingerprint does not match expected fingerprint

The PBS TLS certificate changed since Proxmox VE first trusted it — usually after a certificate renewal, a PBS reinstall, or a hostname change. Fix: in PVE, edit the PBS storage entry (Datacenter → Storage), clear the fingerprint field, and re-fetch/approve the current fingerprint. Verify out-of-band that the new fingerprint is really your server before trusting it; this error is also exactly what a machine-in-the-middle would produce.

connection refused / connection timed out on port 8007

proxmox-backup-client ... failed: connection error:
Connection refused (os error 111)

PVE cannot reach the PBS API port. Work outward: is proxmox-backup-proxy running on the PBS host (systemctl status proxmox-backup-proxy)? Does the PBS firewall allow TCP 8007 from the PVE host? Is there a NAT or upstream firewall in the path? A quick probe from the PVE node isolates the layer: if the TCP connect fails, it is network/firewall; if TCP connects but the API call fails, it is service or auth.

authentication failed - invalid credentials

authentication failed - invalid credentials

Three usual causes. First, API token syntax: the username for a token is user@realm!tokenname — the exclamation section is part of the username, not the password, and the secret goes in the password field. Second, the token or user lacks permissions on the datastore path (needs DatastoreBackup or higher on /datastore/<name>). Third, clock skew: PBS tickets are time-sensitive, so a PVE node with drifted time can fail auth — check NTP on both ends.

datastore 'X' is full / ENOSPC

TASK ERROR: could not get chunk store lock: ENOSPC: no space left on device

Backups are failing because the datastore has no space. The recovery sequence matters: run prune to drop out-of-retention snapshots, then run garbage collection — and expect the space to return only on the GC run after roughly 24 hours have passed (see the next entry for why). If you are hard-full and GC itself cannot run, remove an old unprotected snapshot group manually to free working room, then follow the normal sequence. Long term: alert at 80% usage, not at failure.

Garbage collection runs but frees no space

TASK OK — removed garbage: 0 B
pending removals: 1.82 TiB (in 24h 5m)

Almost always one of two things. One: nothing was pruned — GC only removes chunks no snapshot references, so if retention still keeps the snapshots, every chunk is still referenced. Two: the 24h05m access-time grace window — GC will not remove chunks whose atime is newer than 24 hours 5 minutes, a safety property protecting in-flight backups. Prune first, wait a day, run GC again. If space still does not return, check for forgotten snapshot groups in other namespaces referencing the same chunks, and confirm the datastore filesystem was not mounted with atime fully disabled.

verification failed on snapshot

verify datastore1:vm/101/2026-06-14T02:00:09Z
  chunk b0f2... verification failed
TASK ERROR: verification failed - please check the log for details

A chunk failed its checksum — the data on disk no longer matches what was written. The snapshot is flagged bad, and the next backup of that guest will re-upload the affected chunks if the source still has the data, which often self-heals the group. Treat the cause seriously: one failure is a warning, a pattern across snapshots is failing storage — check SMART on the datastore disks and, if on ZFS, run a scrub and read zpool status. Do not delete the failed snapshot until a newer verified one exists.

backup group is locked / unable to acquire lock

TASK ERROR: unable to acquire lock on backup group vm/101 - another backup is already running

Two tasks tried to touch the same backup group at once — commonly an overlapping backup and prune/verify, a sync job colliding with a backup, or a previous task that died and left its lock behind. Check the running task list on PBS and let genuine tasks finish. If no task is actually running, the stale lock clears on its own shortly, or restart the proxmox-backup-proxy service to release it immediately. Recurring collisions mean your schedules overlap: stagger them (see our backup windows guide).

dirty-bitmap status: created new (every single backup)

INFO: dirty-bitmap status: created new

Not an error, but a performance flag worth chasing: the incremental tracking bitmap is being rebuilt each run, so every backup re-reads the full disk instead of only changed blocks. The bitmap lives in QEMU memory and is lost when the VM stops, migrates, or the node reboots. Seeing it constantly means something restarts the VM between backups — nightly reboots inside the guest, HA migrations, or memory ballooning-driven restarts. Fix the restart cause and incremental speed returns.

Rather never debug the server side again?

On our hosted PBS, the storage, service, and platform-level failures in this list become our pager, not yours. From $6.95/month.

See plans

Diagnosis order

  • Read the full task log, not the summary line
  • Network → service → auth → storage, in that order
  • Check the PBS task list before assuming a hang
  • One bad chunk = disk warning; many = disk failure
  • Space math: prune → 24h → GC

Related guides