proxmox-snapshot-service/handbuch/docs/nachschlagen/fehlersuche.md

# Fehlersuche

## Es passiert gar nichts

Der Dienst läuft, das Protokoll ist ruhig, und trotzdem entstehen keine
Snapshots.

```bash
pvesnap status        # hat eine Gruppe einen nächsten Termin?
pvesnap vms           # steht überhaupt eine VM in einer Gruppe?
pvesnap check
```

| Ursache | |
|---|---|
| **Alle Gruppen auf `enabled = no`** | So wird ausgeliefert. Der häufigste Fall. |
| Auswahl trifft auf nichts zu | Tag falsch geschrieben? `pvesnap vms` zeigt es. |
| `dry_run = yes` in `[global]` | Es wird nur protokolliert. |
| Konfiguration nach der Änderung nicht neu geladen | `systemctl reload pvesnap` |

---

## Storage-Lock

```
trying to acquire cfs lock 'storage-data' ...
TASK ERROR: cfs-lock 'storage-data' error: got lock request timeout
```

!!! note "`storage-data` ist kein falsch gelesener Name"

    In pmxcfs heißen Storage-Sperren immer `storage-<name>`. Gemeint ist also
    das Storage `data`.

Proxmox nimmt diese Sperre beim Anlegen eines Snapshots und gibt nach 60
Sekunden auf, wenn sie jemand anderes hält.

pvesnap geht damit so um:

* Der Aufruf **wartet, bis der Proxmox-Task wirklich fertig ist**, bevor die
  nächste VM drankommt — sonst würden sich die eigenen Läufe aussperren
* Sperr-Fehler gelten als vorübergehend und werden `retries`-mal mit
  `retry_delay` Abstand wiederholt
* Echte Fehler (etwa „storage does not support snapshots") werden **nicht**
  wiederholt
* `pause_between = 10s` nimmt zusätzlich Druck vom Storage

### Der Dienst scheitert, von Hand geht es

Das ist der Fall, an dem man am längsten sucht — und er hat mit dem Storage
nichts zu tun.

!!! danger "Sandbox-Optionen in der systemd-Unit"

    `pvesh` führt die Proxmox-API im eigenen Prozess aus. Der Snapshot-Task ist
    also ein **Kindprozess von pvesnap** und erbt alles, was in der Unit
    eingeschränkt wurde.

    `ProtectSystem=` hängt `/etc` schreibgeschützt ein — und pmxcfs legt seine
    Sperren als **Verzeichnisse** unter `/etc/pve/priv/lock/` an. Das `mkdir`
    scheitert, Proxmox wiederholt es erfolglos und meldet am Ende einen
    Lock-Timeout statt eines Rechtefehlers.

Prüfen:

```bash
systemctl show pvesnap -p ProtectSystem -p ProtectHome -p PrivateTmp -p ReadOnlyPaths
pvesnap check          # meldet so etwas von sich aus
```

Alle müssen leer bzw. `no` sein. Die mitgelieferte Unit enthält deshalb
**bewusst keine** Sandbox-Optionen.

`ProtectHome=yes` hat denselben Effekt an anderer Stelle: Es ersetzt `/root`
durch ein leeres Verzeichnis — und Proxmox erreicht andere Cluster-Nodes über
die SSH-Schlüssel in `/root/.ssh`.

### Wenn die Sperre wirklich belegt ist

```bash
pvesm status                      # ist das Storage online und erreichbar?
grep -A6 "^[a-z]*: data" /etc/pve/storage.cfg
pvesh get /cluster/tasks --output-format json | head    # hängt noch ein Task?
systemctl status pvestatd pve-cluster
journalctl -u pvestatd -n 50
```

Häufigste Ursachen: ein hängender Backup- oder Replikationsjob auf demselben
Storage, ein nicht erreichbares NFS/CIFS-Storage (dann blockiert `pvestatd`),
oder ein abgebrochener Task, der die Sperre nicht freigegeben hat.

---

## `snapshot is protected`

```
TASK ERROR: rbd snapshot 'auto-taeglich-20260809-023000' is protected from removal
```

Am Snapshot hängt ein Klon — also eine
[Wiederherstellung](../wiederherstellen/index.md). Das ist zunächst richtig so:
Ceph verlangt den Schutz, solange ein Klon existiert.

| Lage | |
|---|---|
| Die Wiederherstellung wird noch gebraucht | Nichts tun. Der Snapshot bleibt eben liegen. |
| Sie wird nicht mehr gebraucht | `pvesnap-recovery destroy <VMID>` |
| Sie soll bleiben | `pvesnap-recovery flatten <VMID>` |
| Sie wurde in der **Weboberfläche** gelöscht | `pvesnap-recovery cleanup` |

Der letzte Fall ist der, den man sonst nicht findet: Der Klon ist weg, der
Schutz steht noch, und die Vorhaltezeit scheitert für immer.

Nachsehen:

```bash
rbd -p <pool> snap ls vm-101-disk-0      # Spalte PROTECTED
rbd -p <pool> ls -l | grep vm-101        # gibt es noch Klone?
```

---

## `storage does not support snapshots`

Die VM liegt auf LVM-thick oder auf einem `raw`-Image in einem
Verzeichnis-Storage. Dort kann Proxmox keine Snapshots — pvesnap überspringt sie
und macht mit den übrigen weiter.

Der Ausweg ist ein Umzug:

```bash
qm move-disk 101 scsi0 <thin-oder-ceph-storage>
```

Siehe [Speicherarten](speicher.md).

---

## Der Snapshot lässt sich nicht einbinden

```bash
pvesnap-explorer --cleanup      # erst einmal aufräumen
pvesnap-explorer -v 101         # dann mit ausführlichem Protokoll
```

| Meldung | |
|---|---|
| `rbd: image uses unsupported features` | Der Kernel kann das Image nicht direkt; pvesnap weicht auf `rbd-nbd` aus. Fehlt das Paket `rbd-nbd`, nachinstallieren. |
| `unknown filesystem type` | Das Dateisystem im Gast kennt der Host nicht (z. B. Btrfs ohne Modul, oder ReFS). |
| `wrong fs type … or superblock corrupt` | Meist eine verschlüsselte Partition (LUKS, BitLocker). Dort führt nur der Weg über eine [laufende Maschine](../wiederherstellen/index.md). |
| Es wird gar kein Dateisystem angeboten | Reine Datenplatte ohne Partitionstabelle, oder LVM im Gast, das nicht aktiviert werden konnte. |

Reste nach einem Absturz aufspüren:

```bash
findmnt | grep pvesnap
rbd showmapped
losetup -a
ls /run/pvesnap/
```

---

## Die Maschine startet, aber der RAM-Zustand fehlt

Symptom: Die Wiederherstellung bootet, statt weiterzulaufen. Die Uhr im Gast
zeigt die aktuelle Zeit statt der Snapshot-Zeit.

!!! warning "Proxmox meldet das als `TASK OK`"

    Schlägt das Laden fehl, quittiert Proxmox den Start trotzdem mit Erfolg und
    lässt die Maschine in `prelaunch` stehen. `pvesnap-recovery` liest das
    Task-Protokoll mit, setzt sie fort und sagt es deutlich.

| Meldung im Task-Protokoll | |
|---|---|
| `Size mismatch: vga.vram` | SPICE (`vga: qxl`) und geladener Arbeitsspeicher schließen sich aus. Siehe [Dongle und USB](../wiederherstellen/dongle.md#spice-und-geladener-arbeitsspeicher-schlieen-sich-aus). |
| `Unknown savevm section or instance 'vmgenid'` | Die Geräteausstattung passt nicht zum gespeicherten Zustand. Tritt bei von Hand veränderten Konfigurationen auf. |
| `unable to open vmstate` | Der Arbeitsspeicher-Datenträger ist nicht mehr da — Proxmox gibt ihn nach dem **ersten** Start frei. Ein zweiter Start bootet immer kalt. |

Der letzte Punkt ist kein Fehler, sondern das erwartete Verhalten. Wer den
warmen Zustand braucht, arbeitet damit **beim ersten Start**.

---

## Das Austauschlaufwerk lässt sich nicht auswerfen

```
'dumps' liess sich nicht abziehen: ...
Meist haelt der Gast es noch - dort erst aushaengen
(Linux: umount, Windows: Auswerfen im Explorer).
```

Genau das ist es meistens. Im Gast aushängen, dann noch einmal ++e++.

Weitere Fälle:

| Meldung | |
|---|---|
| `ist gerade in Benutzung von 9101` | Das Laufwerk steckt in einer anderen Maschine. Dort auswerfen. |
| `ist gerade am Host eingehängt` | Mit ++u++ in der Laufwerksübersicht aushängen. |
| `Bei Containern gibt es nichts auszuwerfen` | Dort ist es ein durchgereichtes Verzeichnis — Host und Gast sehen dieselben Dateien ohnehin gleichzeitig. |

---

## SPICE oder USB gehen nicht

| Symptom | |
|---|---|
| Maschine startet nicht, `no spice port` | `vga: qxl` fehlt. Detailansicht ++p++ → SPICE ein. |
| Kein Eintrag unter „USB-Geräteauswahl" | Der `remote-viewer` läuft nicht auf dem Rechner, an dem der Dongle steckt. |
| `.vv`-Datei wird abgewiesen | Sie ist zu alt — das Kennwort darin gilt nur wenige Sekunden. Neu erzeugen. |
| `remote-viewer` nicht gefunden | Paket `virt-viewer` installieren. |

Mehr unter [Dongle und USB](../wiederherstellen/dongle.md#wenn-der-dongle-nicht-auftaucht).

---

## Die Web-Oberfläche zeigt keine Gäste

Ein angemeldeter Benutzer sieht nur Gäste, auf denen er das Recht
**`VM.Snapshot`** hat. Ist die Liste leer, fehlt genau das.

```bash
pveum user permissions <benutzer>@<realm>
```

Anpassen mit `--require-privilege VM.Backup` oder
`--allow-user <benutzer>@<realm>` in `/etc/pvesnap/web.conf`, danach
`systemctl restart pvesnap-web`.

Fehlgeschlagene Anmeldungen stehen mit Absender-IP im Journal:

```bash
journalctl -u pvesnap-web -n 50
```

---

## Der Port ist belegt

Beim Installieren:

```
Auf Port 8823 laeuft bereits ein anderer Prozess (PID 12345)
```

Das ist eine Warnung, kein Abbruch — es könnte etwas ganz anderes sein. Nachsehen:

```bash
ss -lntp | grep 8823
```

Eine bereits laufende `pvesnap-web` wird dagegen von selbst sauber angehalten
und danach wieder gestartet.

---

## Zeitpläne stimmen nicht

| Beobachtung | |
|---|---|
| Der Termin liegt eine Stunde daneben | Zeitumstellung. Es wird mit lokaler Zeit gerechnet. |
| Nach einem Neustart kam sofort ein Lauf | Ein verpasster Termin wird nachgeholt — einmal, nicht für jeden ausgefallenen. |
| Im Februar fiel der Monatslauf aus | Sollte nicht passieren: `day_of_month = 31` wird auf den Monatsletzten gezogen. Prüfen mit der Vorschauzeile in der [Gruppenmaske](../sichern/editor.md#eine-gruppe-bearbeiten). |
| Die Snapshots liegen auf krummen Zeiten | `align = no`. Mit `align = yes` richten sie sich an der Uhr aus. |

---

## Wenn gar nichts mehr hilft

```bash
pvesnap -v check                        # ausführlich
pvesnap -v run --force --dry-run        # zeigt jeden pvesh-Aufruf
journalctl -u pvesnap -n 200 --no-pager
```

Mit `log_level = DEBUG` in `[global]` protokolliert der Dienst jeden
`pvesh`-Aufruf mit allen Argumenten. Damit lässt sich der fehlschlagende Aufruf
von Hand nachstellen — und dann sieht man die echte Meldung von Proxmox statt
der aufbereiteten.