proxmox-backup-client errors: the exact message, the cause, the command

Error: client error (Connect)

Cause. The client could not open the TCP connection to the PBS. We reproduced this message in three different cases: port 8007 closed, unreachable IP address and non-existent DNS name. The message is identical in all three: it does not tell you which one applies.

getent hosts pbs.example.com          # does the name resolve?
nc -vz pbs.example.com 8007             # does the port answer?
curl -kv https://pbs.example.com:8007/  # do TLS and HTTP answer?

Fix. Fix the name or address in the repository (PBS_REPOSITORY), open 8007/TCP on the firewall between client and PBS, and check on the PBS that the service is running.

systemctl status proxmox-backup-proxy   # on the PBS

Source : reproduit avec proxmox-backup-client 4.2.5 le 08/10/2026 (port fermé, IP injoignable, nom DNS inexistant)

Error: error trying to connect: error connecting to https://192.168.0.101:8007/ - tcp connect error: deadline has elapsed

Cause. The TCP connection did not complete within the 10-second timeout. Most often a firewall drops packets without answering, or routing to the PBS is wrong (VLAN, gateway, duplicate IP).

nc -vz -w 5 192.168.0.101 8007
traceroute -T -p 8007 192.168.0.101

Fix. Open 8007/TCP end to end. Proxmox staff point out on the forum that the firewall must also let HTTP/2 through.

Source : https://forum.proxmox.com/threads/error-error-trying-to-connect-error-connecting-to-ip-tcp-connect-error-deadline-has-elapsed.107038/ ; gabarit proxmox/proxmox-http/src/client/connector.rs:244

Error: http request timed out

Cause. The connection is open, but the PBS does not answer the request in time. Common causes: a firewall dropping packets along the way, or an overloaded server (verify or garbage collection on slow disks).

curl -kv --max-time 30 https://pbs.example.com:8007/
proxmox-backup-manager task list        # on the PBS: running tasks

Fix. Check the firewall along the whole path, and move heavy PBS tasks out of the backup window.

Source : proxmox-backup 4.2.8, pbs-client/src/http_client.rs:961

HTTP/2.0 connection failed

Cause. The HTTP/2 connection was cut during the backup. It is often followed by "Error: broken pipe", or on PVE by "backup write data failed: command error: protocol canceled". Forum threads cite a failing power supply, a network card whose TSO/GSO offload misbehaves, or a device that cuts long-lived connections.

dmesg -T | grep -iE 'eth|eno|ens|link'
ethtool -k eno1 | grep -E 'tcp-segmentation|generic-(segmentation|receive)'

Fix. Look for the cut on the network side. On an e1000e card, a forum author solved it by disabling offloading; test it, do not apply it everywhere.

ethtool -K eno1 tso off gso off gro off   # test, not persistent

Source : proxmox-backup 4.2.8, pbs-client/src/http_client.rs:927 ; https://forum.proxmox.com/threads/error-message-during-backup-exit-code-255.84130/

certificate validation failed - Certificate fingerprint was not confirmed.

Cause. The PBS presents a certificate the client cannot validate (self-signed, or unknown authority), and nobody confirmed its fingerprint. Interactively, the client prints the fingerprint then "Are you sure you want to continue connecting? (y/n): "; in a script, a cron job or Proxmox VE it cannot ask, and fails with this message.

proxmox-backup-manager cert info | grep -i fingerprint   # on the PBS

Fix. Give the client the fingerprint, after comparing it with the PBS one. With a certificate signed by a recognised authority (ACME, Let's Encrypt), no fingerprint is needed. Outside Debian, a binary extracted by hand may find no certificate authority at all: see our Linux guide.

export PBS_FINGERPRINT='aa:bb:cc:…'   # 32 hex pairs

Source : proxmox-backup 4.2.8, pbs-client/src/http_client.rs:451

WARNING: certificate fingerprint does not match expected fingerprint!

Cause. The fingerprint provided (PBS_FINGERPRINT, --fingerprint, or the storage fingerprint field in Proxmox VE) no longer matches the certificate presented. Typical cases: renewed certificate, switch to ACME, or connecting to another server than expected.

proxmox-backup-manager cert info | grep -i fingerprint   # on the PBS
grep -A6 '^pbs:' /etc/pve/storage.cfg                    # on Proxmox VE

Fix. First check you are talking to the right server, then update the fingerprint where it is stored. The client also keeps confirmed fingerprints in ~/.config/proxmox-backup/fingerprints.

Source : proxmox-backup 4.2.8, pbs-client/src/http_client.rs:707

Error: error trying to connect: error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed

Cause. OpenSSL rejects the certificate. Thread 89200 gives a common cause: the repository uses a short name or an IP address, while the certificate is issued for the full name (FQDN). The suffix of the message (.c file and line number) varies with the OpenSSL version.

openssl s_client -connect pbs.example.com:8007 -servername pbs.example.com </dev/null | openssl x509 -noout -subject -ext subjectAltName

Fix. Use in the repository exactly the name found in the certificate, or provide the fingerprint if the certificate is self-signed.

Source : https://forum.proxmox.com/threads/proxmox-backup-client-certificate-check.98680/ ; https://forum.proxmox.com/threads/unable-to-run-host-backups-anymore-tls-certificate-verify-failed.89200/

Error: HTTP Error 401 Unauthorized: permission check failed.

Cause. The connection is refused at authentication: wrong password or token secret, non-existent user, or wrong realm (@pbs instead of @pam, or the reverse). The message never says "authentication failed": it is this exact text, with a final full stop.

journalctl -u proxmox-backup-proxy | grep 'authentication failure'   # on the PBS

Fix. The PBS log gives the exact reason ("authentication failure; rhost=… user=… msg=…"). Check the repository form: user@realm, or user@realm!token for an API token, and the secret in PBS_PASSWORD.

Source : https://forum.proxmox.com/threads/error-http-error-401-unauthorized-permission-check-failed.72832/ ; proxmox/proxmox-auth-api/src/api/access.rs:282

missing permissions 'Datastore.Backup' on '/datastore/store1'

Cause. Authentication succeeded, but the user or token lacks the requested privilege on this datastore. Classic trap: an API token has no more rights than its user, and it needs its own permissions.

proxmox-backup-manager user permissions 'backup@pbs!pve' --path /datastore/store1   # on the PBS

Fix. Add the missing permission on the datastore path, for both the user and the token. Older versions worded this message differently: "permission check failed - missing Datastore.Audit|Datastore.Backup on /datastore/…".

Source : proxmox-backup 4.2.8, pbs-config/src/cached_user_info.rs:137 (HTTP 403)

Error: backup owner check failed (sysadmin@pbs!backups != sysadmin@pbs)

Cause. Each backup group (vm/100, host/srv1…) has an owner. You are writing into a group created by another user or token: on the left the identity used, on the right the owner. Common case: switching from a user to an API token, or reusing a VM ID across two clusters.

proxmox-backup-client list   # owner column

Fix. Back up with the owning identity, or transfer the group to the new identity (requires Datastore.Modify). The group's owner file stays in place even when the group is empty.

proxmox-backup-client change-owner vm/100 'sysadmin@pbs!backups'

Source : proxmox-backup 4.2.8, src/api2/backup/mod.rs:160 ; https://forum.proxmox.com/threads/backup-owner-check-failed-when-trying-to-perform-local-backup.139417/

Error: missing key - manifest was created with key f2:aa:…

Cause. The snapshot was encrypted or signed with a key, and you are reading it (restore, catalog, mount) without a key: neither --keyfile nor a default key in ~/.config/proxmox-backup/encryption-key.json. The fingerprint shown is that of the expected key.

proxmox-backup-client key show /path/encryption-key.json   # fingerprint of your key

Fix. Run again with the key whose fingerprint matches. Without that key or a paper copy, the data cannot be recovered: nobody, neither the PBS host nor Proxmox, can decrypt it.

proxmox-backup-client restore <snapshot> root.pxar /tmp/restore --keyfile /path/encryption-key.json

Source : proxmox-backup 4.2.8, pbs-datastore/src/manifest.rs:180 ; https://forum.proxmox.com/threads/how-to-restore-a-vm-from-encrypted-pbs-via-cli.130893/

Error: wrong key - unable to verify signature since manifest's key ec:c5:b2:0d:… does not match provided key 48:07:92:b1:…

Cause. You do provide a key, but not the one used for this snapshot. Short variant of the same case: "wrong key - manifest's key … does not match provided key …". On Proxmox VE, the message is prefixed with "proxmox-backup-client failed: ".

Fix. Find the key whose fingerprint is quoted on the left (file backup, paper copy, or RSA master key). You cannot change the key of an existing backup afterwards: in Proxmox VE, create a second storage pointing to the same datastore with the other key.

proxmox-backup-client key import-with-master-key /root/restored-key.json \
  --master-keyfile /root/master-private.pem --encrypted-keyfile /root/encrypted-key.blob

Source : proxmox-backup 4.2.8, pbs-datastore/src/manifest.rs:187 et :239 ; https://forum.proxmox.com/threads/change-the-encryption-key-for-one-backup.133861/

Unable to decrypt key (wrong password?)

Cause. The key file is protected by a passphrase, and the one provided is wrong. If the key has a hint, the message becomes "Unable to decrypt key (password hint: …)".

proxmox-backup-client key show /path/encryption-key.json   # asks for the passphrase again

Fix. Find the right passphrase. For a scheduled backup, pass it through the PBS_ENCRYPTION_PASSWORD variable, or use a key without passphrase (--kdf none) protected by file permissions.

Source : proxmox-backup 4.2.8, pbs-key-config/src/lib.rs:215

Error: unable to get (default) repository

Cause. Neither --repository nor the PBS_REPOSITORY variable is set. Common in a cron job or systemd unit, which do not load your shell environment.

Fix. Set the repository as user@realm!token@server:port:datastore (port 8007 is implicit), in an environment file loaded by the cron job or unit.

export PBS_REPOSITORY='backup@pbs!srv01@pbs.example.com:8007:store1'

Source : proxmox-backup 4.2.8, pbs-client/src/tools/mod.rs:293

Error: no such datastore 'newencryptedaccess'

Cause. The datastore name in the repository does not exist on this PBS. In the thread quoted, the user had put the Proxmox VE storage name instead of the PBS datastore name. Without any permission on that path, you first get a permission error.

proxmox-backup-manager datastore list   # on the PBS

Fix. Use the exact datastore name on the PBS side (datastore field of the storage in /etc/pve/storage.cfg).

Source : https://forum.proxmox.com/threads/how-to-restore-a-vm-from-encrypted-pbs-via-cli.130893/ ; gabarit proxmox/proxmox-section-config/src/lib.rs:168

unable to acquire backup group lock

Cause. Another operation is already using the same backup group: most often, two backups of the same VM or host at the same time (two overlapping Proxmox VE jobs, or a manual backup during the scheduled one). On a datastore with the older lock scheme, the text is "unable to acquire lock on backup group directory … - possible runing backup, group is in use" (the "runing" typo is in the code).

proxmox-backup-manager task list   # on the PBS: who holds the group?

Fix. Wait for the other task to finish, or shift the jobs so they do not overlap. Old wording, before PBS 3.4.0 (April 2025), still quoted on the forum: "another backup is already running" and "locked by another operation".

Source : proxmox-backup 4.2.8, pbs-datastore/src/backup_info.rs:473 ; ancien libellé : backup_info.rs:463-466

ENOSPC: No space left on device

Cause. The datastore disk, or the PBS system disk, is full. On the backup side it appears inside "inserting chunk on store '…' failed for …"; on the server side it can even block garbage collection itself ("update atime failed for chunk/file … - ENOSPC: No space left on device").

df -h / /mnt/datastore/store1
proxmox-backup-manager garbage-collection status store1

Fix. Free a few MB (logs, temporary files) so garbage collection can run, then start it. Never delete files by hand in .chunks. The space of unused chunks only comes back after garbage collection, which by default only removes chunks unused for more than 24 h 5 min.

proxmox-backup-manager garbage-collection start store1

Source : https://forum.proxmox.com/threads/proxmox-backup-server-issue.89728/ ; https://forum.proxmox.com/threads/disk-full-unable-to-run-garbage-collection.81800/ ; pbs-datastore/src/chunk_store.rs:768

backup ended but finished state is not set.

Cause. Server message: the backup connection closed before the client announced completion. The PBS records the interruption and removes the incomplete snapshot. The real reason is on the client or network side: cut, killed client, memory exhausted, abandoned VSS snapshot.

Fix. Read the client or Proxmox VE task log at the same timestamp: the first error is there.

Source : proxmox-backup 4.2.8, src/api2/backup/environment.rs:923

can't verify missing chunk with digest …

Cause. A chunk referenced by a snapshot no longer exists in the datastore. On restore, the message becomes "cannot find chunk with digest …". Causes seen on the forum: manual deletion in .chunks, failing disk, chunk truncated after a hard shutdown ("blob too small (0 bytes).").

dmesg -T | grep -iE 'error|fail'   # on the PBS
zpool status -v                     # if the datastore is on ZFS

Fix. Once a verify has marked the snapshot as failed, the next backup sends the missing chunks again; an older snapshot can only be repaired from another copy (sync from a second PBS). This is the case for a second copy, off the same disk.

Source : proxmox-backup 4.2.8, src/backup/verify.rs:308 ; restauration : src/api2/reader/mod.rs:358

VSS (Shadow Copy) nécessite les privilèges administrateur - veuillez redémarrer l'application en tant qu'administrateur ou désactiver VSS

Cause. The GUI was started without elevation while the backup uses a VSS snapshot, which requires administrator rights. The message is in French in the code, whatever the Windows language.

Fix. Restart the client as administrator, or schedule the backup with an account that has those rights.

Source : proxmoxbackupclient_go, gui/main.go:666 (amont) / :683 (fork)

VSS busy while building a multi-volume snapshot set

Cause. Another VSS snapshot is in progress: another backup tool, Windows Backup, or a hypervisor snapshot. The client tries once to reset the VSS service ("Resetting VSS service state and retrying once...") before giving up.

vssadmin list writers
vssadmin list shadows

Fix. Shift schedules so no other tool takes a snapshot at the same time.

Source : proxmoxbackupclient_go, snapshot/win_snapshot.go:137

VSS snapshot creation failed

Cause. Windows refused to create the snapshot. Usual causes: a VSS writer in error, or not enough shadow storage on the volume. The client's non-blocking warnings ("System Writer has errors", "NTDS Writer refuses to participate", "DHCP Jet Writer has errors") point at the writer involved.

vssadmin list writers
vssadmin list shadowstorage

Fix. Restart the service behind the failing writer, or enlarge the shadow storage.

vssadmin resize shadowstorage /for=C: /on=C: /maxsize=10%

Source : proxmoxbackupclient_go, snapshot/win_snapshot.go:161

certificate fingerprint does not match (expected …, got …)

Cause. The fingerprint set in the client configuration does not match the PBS certificate. Same cause as on Linux: renewed certificate, or wrong server.

Fix. Copy the fingerprint shown by the PBS (dashboard, Show Fingerprint), in aa:bb:… format, after checking the server.

Source : proxmoxbackupclient_go, pbscommon/pbsapi.go:234 (amont) / :239 (fork)

authentication failed: invalid credentials

Cause. The connection test got an HTTP 401 refusal: wrong ID, realm or secret. If the test passes but the backup fails with "access denied: check datastore permissions", that is a 403: the identity is right, but it lacks rights on the datastore.

Fix. Check the user@realm!token form and the secret, then the token's permissions on the datastore.

Source : proxmoxbackupclient_go, pbscommon/pbsapi.go:929 (amont) / :921 (fork)

connection lost: PBS session cannot be resumed (reconnect blocked to prevent orphaned sessions)

Cause. The connection to the PBS was cut during the backup. The client does not resume the session, so as not to leave an orphaned session on the server; on the PBS side the task ends with "backup ended but finished state is not set.".

Fix. Find the cut (Wi-Fi, sleep, renegotiating VPN) and run the backup again.

Source : proxmoxbackupclient_go, pbscommon/pbsapi.go:999 (amont) / :991 (fork)