Erreurs de proxmox-backup-client : le message exact, la cause, la commande

Error: client error (Connect)

Cause. Le client n'a pas pu ouvrir la connexion TCP vers le PBS. Nous avons reproduit ce message dans trois cas différents : port 8007 fermé, adresse IP injoignable et nom DNS inexistant. Le message est identique dans les trois cas : il ne dit pas lequel s'applique.

getent hosts pbs.example.com          # le nom se résout-il ?
nc -vz pbs.example.com 8007             # le port répond-il ?
curl -kv https://pbs.example.com:8007/  # TLS et HTTP répondent-ils ?

Correctif. Corriger le nom ou l'adresse dans le dépôt (PBS_REPOSITORY), ouvrir 8007/TCP sur le pare-feu entre le client et le PBS, et vérifier sur le PBS que le service tourne.

systemctl status proxmox-backup-proxy   # sur le 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. La connexion TCP n'a pas abouti dans le délai de 10 secondes. Le plus souvent, un pare-feu jette les paquets sans répondre, ou le routage vers le PBS est faux (VLAN, passerelle, IP dupliquée).

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

Correctif. Ouvrir 8007/TCP de bout en bout. Le staff Proxmox rappelle sur le forum que le pare-feu doit aussi laisser passer HTTP/2.

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. La connexion est ouverte, mais le PBS ne répond pas à la requête dans le délai. Causes fréquentes : un pare-feu qui jette les paquets en cours de route, ou un serveur saturé (verify ou garbage collection sur des disques lents).

curl -kv --max-time 30 https://pbs.example.com:8007/
proxmox-backup-manager task list        # sur le PBS : tâches en cours

Correctif. Vérifier le pare-feu sur tout le trajet, et décaler les tâches lourdes du PBS hors de la fenêtre de sauvegarde.

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

HTTP/2.0 connection failed

Cause. La connexion HTTP/2 a été coupée pendant la sauvegarde. Il est souvent suivi de « Error: broken pipe », ou côté PVE de « backup write data failed: command error: protocol canceled ». Les fils du forum citent une alimentation défaillante, une carte réseau dont le déchargement TSO/GSO pose problème, ou un équipement qui coupe les longues connexions.

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

Correctif. Chercher la coupure côté réseau. Sur une carte e1000e, un auteur du forum a résolu le problème en désactivant le déchargement ; à tester, pas à appliquer partout.

ethtool -K eno1 tso off gso off gro off   # test, non persistant

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. Le PBS présente un certificat que le client ne peut pas valider (auto-signé, ou autorité inconnue), et personne n'a confirmé son empreinte. En interactif, le client affiche l'empreinte puis « Are you sure you want to continue connecting? (y/n): » ; dans un script, un cron ou Proxmox VE, il ne peut pas demander et échoue avec ce message.

proxmox-backup-manager cert info | grep -i fingerprint   # sur le PBS

Correctif. Fournir l'empreinte au client, après l'avoir comparée à celle du PBS. Avec un certificat signé par une autorité reconnue (ACME, Let's Encrypt), aucune empreinte n'est nécessaire. Hors Debian, un binaire extrait à la main peut ne trouver aucune autorité de certification : voir notre guide Linux.

export PBS_FINGERPRINT='aa:bb:cc:…'   # 32 paires hexadécimales

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

WARNING: certificate fingerprint does not match expected fingerprint!

Cause. L'empreinte fournie (PBS_FINGERPRINT, --fingerprint, ou le champ fingerprint du stockage dans Proxmox VE) ne correspond plus au certificat présenté. Cas typiques : certificat renouvelé, passage à ACME, ou connexion à un autre serveur que prévu.

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

Correctif. Vérifier d'abord que vous parlez au bon serveur, puis mettre à jour l'empreinte là où elle est stockée. Le client garde aussi les empreintes confirmées dans ~/.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 refuse le certificat. Le fil 89200 en donne une cause fréquente : le dépôt utilise un nom court ou une adresse IP, alors que le certificat est émis pour le nom complet (FQDN). Le suffixe du message (fichier .c et numéro de ligne) varie selon la version d'OpenSSL.

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

Correctif. Utiliser dans le dépôt exactement le nom présent dans le certificat, ou fournir l'empreinte si le certificat est auto-signé.

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. La connexion est refusée au moment de l'authentification : mauvais mot de passe ou secret de jeton, utilisateur inexistant, ou mauvais royaume (@pbs au lieu de @pam, ou l'inverse). Le message ne dit jamais « authentication failed » : c'est bien ce texte, avec un point final.

journalctl -u proxmox-backup-proxy | grep 'authentication failure'   # sur le PBS

Correctif. Le journal du PBS donne la raison exacte (« authentication failure; rhost=… user=… msg=… »). Vérifier la forme du dépôt : utilisateur@royaume, ou utilisateur@royaume!jeton pour un jeton API, et le secret dans 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. L'authentification a réussi, mais l'utilisateur ou le jeton n'a pas le droit demandé sur ce datastore. Piège classique : un jeton API n'a pas plus de droits que son utilisateur, et il faut lui donner ses propres droits.

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

Correctif. Ajouter la permission manquante sur le chemin du datastore, pour l'utilisateur et pour le jeton. Les anciennes versions formulaient ce message autrement : « 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. Chaque groupe de sauvegarde (vm/100, host/srv1…) a un propriétaire. Vous écrivez dans un groupe créé par un autre utilisateur ou un autre jeton : à gauche l'identité utilisée, à droite le propriétaire. Cas fréquent : passer d'un utilisateur à un jeton API, ou réutiliser un identifiant de VM entre deux clusters.

proxmox-backup-client list   # colonne owner

Correctif. Sauvegarder avec l'identité propriétaire, ou transférer le groupe à la nouvelle identité (droit Datastore.Modify nécessaire). Le fichier owner du groupe reste en place même quand le groupe est vide.

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. Le snapshot a été chiffré ou signé avec une clé, et vous le lisez (restauration, catalogue, montage) sans fournir de clé : ni --keyfile, ni clé par défaut dans ~/.config/proxmox-backup/encryption-key.json. L'empreinte affichée est celle de la clé attendue.

proxmox-backup-client key show /chemin/encryption-key.json   # empreinte de votre clé

Correctif. Relancer avec la clé dont l'empreinte correspond. Sans cette clé ni copie papier, les données ne sont pas récupérables : personne, ni l'hébergeur du PBS ni Proxmox, ne peut les déchiffrer.

proxmox-backup-client restore <snapshot> root.pxar /tmp/restore --keyfile /chemin/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. Vous fournissez bien une clé, mais pas celle qui a servi à ce snapshot. Variante courte du même cas : « wrong key - manifest's key … does not match provided key … ». Côté Proxmox VE, le message est préfixé par « proxmox-backup-client failed: ».

Correctif. Retrouver la clé dont l'empreinte est citée à gauche (sauvegarde du fichier, copie papier, ou clé maître RSA). On ne peut pas changer après coup la clé d'une sauvegarde existante : dans Proxmox VE, créer un second stockage pointant vers le même datastore avec l'autre clé.

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. Le fichier de clé est protégé par une phrase secrète, et celle fournie est fausse. Si la clé a un indice, le message devient « Unable to decrypt key (password hint: …) ».

proxmox-backup-client key show /chemin/encryption-key.json   # redemande la phrase

Correctif. Retrouver la bonne phrase secrète. Pour une sauvegarde planifiée, la fournir par la variable PBS_ENCRYPTION_PASSWORD, ou utiliser une clé sans phrase (--kdf none) protégée par les droits du fichier.

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

Error: unable to get (default) repository

Cause. Ni --repository ni la variable PBS_REPOSITORY ne sont définis. Fréquent dans un cron ou une unité systemd, qui ne chargent pas l'environnement de votre shell.

Correctif. Définir le dépôt sous la forme utilisateur@royaume!jeton@serveur:port:datastore (le port 8007 est implicite), dans un fichier d'environnement chargé par le cron ou l'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. Le nom de datastore du dépôt n'existe pas sur ce PBS. Dans le fil cité, l'utilisateur avait mis le nom du stockage Proxmox VE au lieu du nom du datastore PBS. Sans aucun droit sur ce chemin, vous recevez d'abord une erreur de permission.

proxmox-backup-manager datastore list   # sur le PBS

Correctif. Reprendre le nom exact du datastore côté PBS (champ datastore du stockage dans /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. Une autre opération utilise déjà le même groupe de sauvegarde : le plus souvent, deux sauvegardes de la même VM ou du même hôte en même temps (deux jobs Proxmox VE qui se chevauchent, ou une sauvegarde manuelle pendant le job planifié). Sur un datastore à l'ancien schéma de verrou, le texte est « unable to acquire lock on backup group directory … - possible runing backup, group is in use » (la faute « runing » est dans le code).

proxmox-backup-manager task list   # sur le PBS : qui tient le groupe ?

Correctif. Attendre la fin de l'autre tâche, ou décaler les jobs pour qu'ils ne se chevauchent pas. Anciens libellés, avant PBS 3.4.0 (avril 2025), encore cités sur le forum : « another backup is already running » et « 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. Le disque du datastore, ou le disque système du PBS, est plein. Côté sauvegarde, il apparaît dans « inserting chunk on store '…' failed for … » ; côté serveur, il peut aussi bloquer le garbage collection lui-même (« update atime failed for chunk/file … - ENOSPC: No space left on device »).

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

Correctif. Libérer quelques Mo (journaux, fichiers temporaires) pour que le garbage collection puisse tourner, puis le lancer. Ne jamais supprimer de fichiers à la main dans .chunks. L'espace des blocs devenus inutiles ne revient qu'après le garbage collection, qui par défaut ne retire que les blocs non utilisés depuis plus de 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. Message du serveur : la connexion de sauvegarde s'est fermée avant que le client annonce la fin. Le PBS constate l'interruption et supprime le snapshot incomplet. La vraie raison est côté client ou réseau : coupure, client tué, mémoire saturée, cliché VSS abandonné.

Correctif. Lire le journal du client ou de la tâche Proxmox VE au même horodatage : c'est là que se trouve la première erreur.

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

can't verify missing chunk with digest …

Cause. Un bloc référencé par un snapshot n'existe plus dans le datastore. À la restauration, le message devient « cannot find chunk with digest … ». Causes vues sur le forum : suppression manuelle dans .chunks, disque défaillant, bloc tronqué après un arrêt brutal (« blob too small (0 bytes). »).

dmesg -T | grep -iE 'error|fail'   # sur le PBS
zpool status -v                     # si le datastore est sur ZFS

Correctif. Une fois le snapshot marqué en échec par un verify, la sauvegarde suivante réenvoie les blocs manquants ; un snapshot ancien ne se répare qu'à partir d'une autre copie (synchronisation depuis un second PBS). C'est l'argument d'une seconde copie, hors du même disque.

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. L'interface a été lancée sans élévation alors que la sauvegarde utilise un cliché VSS, qui exige les droits administrateur. Le message est en français dans le code, quelle que soit la langue de Windows.

Correctif. Relancer le client en tant qu'administrateur, ou planifier la sauvegarde avec un compte qui a ces droits.

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

VSS busy while building a multi-volume snapshot set

Cause. Un autre cliché VSS est en cours : autre logiciel de sauvegarde, Sauvegarde Windows, ou cliché d'un hyperviseur. Le client tente une fois de réinitialiser le service VSS (« Resetting VSS service state and retrying once... ») avant d'abandonner.

vssadmin list writers
vssadmin list shadows

Correctif. Décaler les horaires pour qu'aucun autre outil ne prenne de cliché en même temps.

Source : proxmoxbackupclient_go, snapshot/win_snapshot.go:137

VSS snapshot creation failed

Cause. Windows a refusé de créer le cliché. Causes habituelles : un writer VSS en erreur, ou pas assez d'espace réservé aux clichés sur le volume. Les avertissements non bloquants du client (« System Writer has errors », « NTDS Writer refuses to participate », « DHCP Jet Writer has errors ») désignent le writer en cause.

vssadmin list writers
vssadmin list shadowstorage

Correctif. Redémarrer le service lié au writer en erreur, ou agrandir l'espace réservé aux clichés.

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. L'empreinte saisie dans la configuration du client ne correspond pas au certificat du PBS. Même cause que côté Linux : certificat renouvelé, ou mauvais serveur.

Correctif. Recopier l'empreinte affichée par le PBS (tableau de bord, Show Fingerprint), au format aa:bb:…, après avoir vérifié le serveur.

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

authentication failed: invalid credentials

Cause. Le test de connexion a reçu un refus HTTP 401 : identifiant, royaume ou secret faux. Si le test passe mais que la sauvegarde échoue avec « access denied: check datastore permissions », c'est un 403 : l'identité est bonne, mais elle n'a pas les droits sur le datastore.

Correctif. Vérifier la forme utilisateur@royaume!jeton et le secret, puis les permissions du jeton sur le 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. La connexion au PBS a été coupée pendant la sauvegarde. Le client ne reprend pas la session, pour ne pas laisser de session orpheline sur le serveur ; côté PBS, la tâche se termine par « backup ended but finished state is not set. ».

Correctif. Chercher la coupure (Wi-Fi, mise en veille, VPN qui se renégocie) et relancer la sauvegarde.

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