Laufzettel/docs/anleitung/08-fehlerbehebung.md

# Fehlerbehebung

Symptom, Ursache, was zu tun ist. Jede Meldung steht hier so, wie Laufzettel sie zeigt.

## „E-Mail-Adresse oder Passwort stimmt nicht.“

**Ursache:** falsche Zugangsdaten — **oder** ein deaktiviertes Konto. Die Meldung unterscheidet das
nicht, weil sie sonst verriete, welche Adressen es gibt.

**Was tun:** Zugangsdaten prüfen. Bist du sicher, dass sie stimmen, lass einen Administrator unter
**Admin → Benutzer** nachsehen, ob dein Konto auf **aktiv** steht. Ein deaktiviertes Konto wird auch
mit noch gültiger Anmeldung abgewiesen.

## „Der Anbieter war nicht erreichbar. Bitte später erneut versuchen.“

**Ursache:** der Anmeldeanbieter antwortet nicht.

**Was tun:** Gibt es ein lokales Konto, melde dich damit an — genau dafür ist es da. Sonst hilft nur
warten und die Störung melden. Der Notfallzugang steht unter **Admin → Benutzer → Lokales Konto
anlegen** und sollte eingerichtet sein, *bevor* der Anbieter ausfällt.

## „Dafür fehlt dir die Berechtigung“

**Ursache:** deine Rolle darf diese Seite nicht.

**Was tun:** In der Seitenleiste steht ohnehin nur, was du darfst — die Meldung kommt meist von einem
Link, den jemand weitergegeben hat. Brauchst du den Bereich wirklich, lass dir vom Administrator eine
stärkere Rolle geben. Kommt die Rolle vom Anmeldeanbieter, muss sie dort in der Gruppenzuordnung
geändert werden; eine hier gesetzte Rolle wird beim nächsten Anmelden überschrieben.

## „Deine Anmeldung gilt nicht mehr.“

**Ursache:** die Sitzung ist abgelaufen, während das Formular offen stand.

**Was tun:** Genau das, was die Meldung sagt: in einem **zweiten Tab** neu anmelden und dann hier
noch einmal klicken. Was du eingegeben hast, steht weiterhin auf der Seite — **lade sie nicht neu**,
das würde die Eingaben verwerfen.

## Ein Schritt lässt sich nicht speichern

**Ursache und was tun**, in dieser Reihenfolge prüfen:

1. **„… ist archiviert und damit schreibgeschützt.“** — der Lauf ist archiviert. Siehe unten.
2. **„Ein Schritt, der nicht zutrifft, braucht eine Begründung“** oder **„Ein fehlgeschlagener
   Schritt braucht eine Notiz“** — füll das Feld **Begründung** und drück **Mit Begründung
   speichern**. Ohne Begründung stünde im Archiv ein übersprungener Schritt ohne Grund.
3. **Die Pille springt zurück, ohne Meldung** — die Verbindung war weg. Tippe noch einmal. Jeder
   Schritt speichert einzeln, es geht also nur dieser eine Klick verloren.
4. **Nichts passiert, gar nichts** — lade die Seite neu. Ist die Anmeldung abgelaufen, siehst du
   danach die Anmeldeseite und kommst nach dem Anmelden auf dieselbe Stelle zurück.
5. **Deine Rolle ist Leser** — dann gibt es die Pillen nicht, sondern nur die Anzeige des Zustands.
   Läufe bearbeiten darf erst der Techniker.

## Der Lauf lässt sich nicht abschließen

**Ursache:** es ist noch ein Pflichtschritt offen. Der Knopf ist dann gesperrt, und darunter steht,
wie viele es sind; die Meldung nennt die Titel: „Der Lauf lässt sich noch nicht abschließen. Offen
sind: …“

**Was tun:** Die genannten Schritte erledigen — oder, wenn sie nicht zutreffen, mit Begründung als
**nicht zutreffend** eintragen. **Ein fehlgeschlagener Schritt zählt nicht als erledigt:** er ist
entweder zu beheben oder mit Begründung als nicht zutreffend einzutragen. Trifft ein ganzer Abschnitt
nicht zu, nimm **Abschnitt trifft nicht zu** — eine Begründung für achtzehn Schritte.

## Der Lauf ist archiviert

**Ursache:** jemand hat ihn archiviert. Damit ist er schreibgeschützt: kein Haken, kein Wert, keine
Notiz, kein Kommentar geht mehr. Das ist die Zusage, für die das Archiv da ist.

**Was tun:** Prüf zuerst, ob du es wirklich brauchst. Für eine Ergänzung genügt oft ein neuer Lauf,
der auf den alten verweist — das ist der ehrlichere Weg, weil er datiert ist.

Muss es der alte Lauf sein, bittet du einen **Administrator**: nur er sieht auf der Laufseite **aus
dem Archiv zurückholen**. Der Lauf steht danach wieder auf „abgeschlossen“ und lässt sich ändern; das
Zurückholen wird protokolliert.

**Vorbeugen:** archiviere erst, wenn wirklich alles drinsteht. Es gibt keinen Grund zur Eile — ein
abgeschlossener Lauf steht auch schon im Archiv und ist durchsuchbar.

## „Die Datei zu … fehlt im Dateisystem“

**Ursache:** In der Datenbank steht die Zeile eines Anhangs, die Datei selbst ist nicht da. Fast
immer heißt das: es wurde eine Sicherung eingespielt, die nur die Datenbank enthielt. Die Dateien der
Anhänge liegen im Dateisystem, nicht in der Datenbank.

**Was tun:** Das Verzeichnis aus derselben Sicherungsrunde zurückspielen —
`docs/betrieb/sicherung.md` beschreibt beide Wege. Gibt es kein Archiv der Dateien, sind sie weg; die
Zeilen lassen sich dann nur entfernen, indem jemand den Anhang in der Oberfläche löscht.

**Zweitursache, seltener:** nach einer Rücksicherung gehören die Dateien `root` statt dem
Dienstnutzer. Der Dienst kommt dann nicht an sie heran, obwohl sie daliegen:

```bash
sudo ls -l /var/lib/laufzettel/anhaenge
sudo chown -R laufzettel:laufzettel /var/lib/laufzettel/anhaenge
```

**Vorbeugen:** Datenbank und Anhänge im **selben** Skript sichern, direkt hintereinander. Getrennt
gesichert passen die beiden Hälften irgendwann nicht mehr zusammen.

## „Dateien vom Typ … lassen sich nicht anhängen“

**Ursache:** Erlaubt sind Bilder (JPEG, PNG, WebP, HEIC) und PDF. Alles andere wird abgewiesen —
auch SVG, und das ist Absicht: ein SVG ist ein Dokument, das Skripte ausführen kann, und ein Anhang,
den jemand öffnet, soll kein Angriffsweg sein.

**Was tun:** Ein Office-Dokument oder eine Textdatei als PDF ausgeben. Ein Screenshot wird zu PNG,
sobald du ihn speicherst statt ihn aus der Zwischenablage zu ziehen.

## „Kein Laufzettel-Tag“ nach dem Scannen

**Ursache:** einer von drei Fällen, und Laufzettel unterscheidet sie absichtlich nicht — die
Unterscheidung verriete, welche Codes es gibt:

- Es gibt den Code nicht.
- Der Code hat nicht die richtige Form.
- Der Code gehört zu einem **anderen Kunden**.

**Was tun:** Lies den Code unter dem QR ab und vergleich ihn. Ein Laufzettel-Code beginnt mit `LZ-`
und hat sechs Zeichen dahinter, **ohne** die Zeichen `0`, `O`, `1` und `I`. Wer `O` statt `Q` liest,
tippt einen Code, den es nicht geben kann — das ist Absicht, denn ein „verbessertes“ Zeichen könnte
auf ein anderes, vorhandenes Gerät führen.

Stimmt der Code und du siehst trotzdem nichts, gehört der Aufkleber zu einem Kunden, den du nicht
sehen darfst. Frag einen Administrator.

## Der Scanner startet nicht

| Meldung | Ursache | Was tun |
|---|---|---|
| „Die Kamera gibt es nur über HTTPS.“ | die Seite läuft unverschlüsselt | Die verschlüsselte Adresse verwenden. Bis dahin: Code eintippen. |
| „Die Kamera ist nicht freigegeben.“ | Berechtigung verweigert | In den Einstellungen des Browsers die Kamera für diese Seite freigeben und neu laden. |
| „Dieser Browser gibt keine Kamera frei.“ | kein Kamerazugriff möglich | Code eintippen. |
| „Der QR-Leser lässt sich nicht starten.“ | der Decoder ließ sich nicht laden | Seite neu laden. Bleibt es dabei, einem Administrator melden; bis dahin Code eintippen. |
| „Das ist kein Laufzettel-Tag.“ | ein fremder QR-Code im Bild | Den richtigen Aufkleber ins Bild halten — den mit `LZ-…`. |

In allen Fällen gilt: unter dem Kamerabild steht das Feld **Code eintippen**. Der Code steht lesbar
unter dem QR. Ein Scanner, der nicht startet, ist keine Sackgasse.

## Das Etikett wird nicht gelesen

**Ursache und was tun:**

1. **Falsch skaliert gedruckt.** Im Druckdialog **Skalierung auf 100 %** stellen und **Kopf- und
   Fußzeilen abschalten**. „An Seite anpassen“ verkleinert den QR-Code und frisst die Ruhezone am
   Rand, die der Leser braucht.
2. **Der Drucker hat gespart.** Manche Treiber lassen Flächen weg oder drucken sie grau. Ein QR-Code
   braucht harten Schwarz-Weiß-Kontrast; stell den Farbmodus auf normal, nicht auf Toner-Sparen.
3. **Der Aufkleber ist beschädigt oder verschmutzt.** Tipp den Code darunter ein und drucke das
   Etikett neu: auf der Geräteseite **Etikett drucken**. Der Code bleibt derselbe.
4. **Das Etikett sitzt neben der Stanzung.** Dann war die Skalierung falsch — siehe Punkt 1. Das
   Raster des A4-Bogens füllt das Blatt genau aus und verträgt keinen Seitenrand.
5. **Der QR-Code führt ins Leere.** Dann war beim Drucken die Adresse der Anwendung nicht gesetzt
   (die Druckansicht warnt davor in Rot). Ein geklebter Aufkleber lässt sich nicht berichtigen: die
   Adresse eintragen lassen, Etiketten neu drucken und **überkleben**. Der Tag-Code selbst bleibt
   gültig.

## „APP_URL ist nicht gesetzt“

**Ursache:** die Anwendung weiß nicht, unter welcher Adresse sie erreichbar ist. Die QR-Codes zeigen
dann auf `http://localhost:3000` und führen von keinem anderen Gerät irgendwohin.

**Was tun:** **Nicht drucken.** Ein Administrator trägt die Adresse in der Umgebung der Anwendung ein;
in der Oberfläche geht das nicht, weil gedruckte Aufkleber sonst ins Leere zeigen würden. Unter
**Admin → Einstellungen** steht ganz unten, welche Adresse gerade gilt.

## Der Verzeichnisabgleich meldet einen Fehler

| Meldung | Ursache | Was tun |
|---|---|---|
| „… ist keine LDAP-Adresse.“ | Schema fehlt oder falsch | `ldaps://host:636`, `ldap+starttls://host:389` oder `ldap://host:389` eintragen. |
| „In … fehlt der Rechnername.“ | nur das Schema eingetragen | Rechner und Port ergänzen. |
| „… enthält einen Pfad.“ | der Basis-DN steht in der Adresse | Adresse auf Schema, Rechner und Port kürzen; der Basis-DN hat sein eigenes Feld. |
| „… enthält Zugangsdaten.“ | `benutzer@host` in der Adresse | Bind-DN und Passwort in ihre eigenen Felder. |
| „Das Bind-Passwort fehlt.“ | leeres Passwortfeld beim Anlegen | Passwort eintragen; ein anonymer Bind wird nicht unterstützt. |
| Fehler beim Verbinden oder Anmelden | Netz, Firewall, Zertifikat, falsches Dienstkonto | Erreichbarkeit und Port prüfen. Bei einem Zertifikat aus eigener CA das **PEM** hinterlegen. Dann **Verbindung testen**. |
| „Niemand wurde deaktiviert. Prüf die Attributzuordnung, besonders das Kennungsattribut.“ | kein einziger Eintrag ließ sich zuordnen | Das ist die Notbremse: es wurde **nichts** abgeschaltet. Unter **Attributzuordnung anpassen** die **Kennung (dauerhaft)** prüfen — im Active Directory `objectGUID`, im OpenLDAP meist `entryUUID`. |
| „Für … läuft gerade schon ein Abgleich.“ | ein zweiter Lauf, oft der Zeitplan | Abwarten und das **Abgleich-Log** ansehen. |
| „Das CA-Zertifikat muss im PEM-Format vorliegen …“ | falscher Text eingefügt | Der Text muss mit `-----BEGIN CERTIFICATE-----` beginnen. |

**Übersprungene Einträge** im Log sind kein Fehler der Quelle, sondern einzelne krumme Konten. Steigt
die Zahl, prüf die Attributzuordnung.

**Der Abgleich lief, hat aber nichts getan** („0 angelegt, 0 aktualisiert“): das ist die Auskunft,
dass sich im Verzeichnis nichts geändert hat. Alles in Ordnung.

## „Der Entwurf wurde zwischenzeitlich von jemand anderem gespeichert.“

**Ursache:** zwei Redakteure am selben Entwurf.

**Was tun:** **Lade die Seite nicht neu** — deine Eingaben stehen noch da und wären danach weg. Öffne
den Entwurf in einem zweiten Tab, sieh dir die fremde Fassung an und trag deine Änderungen dort nach.
Wird es viel, hilft **Aufbau als JSON herauskopieren** unten an der Speicherleiste: damit rettest du
deinen Stand als Text heraus.

Denselben Ausweg gibt es bei **jedem** fehlgeschlagenen Speichern im Editor, egal woran es lag.

## Der Lauf zeigt einen Platzhalter wie `{{ad_gruppe}}`

**Ursache:** der Platzhalter gehört zu keiner Variablen und zu keinem eingebauten Wert. Im Lauf bleibt
er als Text stehen — sichtbar, aber nutzlos. Meist ein Tippfehler in der Vorlage.

**Was tun:** Im Befehl vor dem Ausführen von Hand ersetzen (der Kasten warnt davor: „konnte nicht
eingesetzt werden und steht so im Befehl“). Dann sag es dem Redakteur: im Editor steht die Warnung
oben, und die Vorlage braucht entweder die Variable oder den richtigen Schlüssel. Das wirkt erst in
der **nächsten** Version — laufende Läufe hängen an ihrer.

## Das Passwort ist weg

**Ursache:** `{{generiertes_passwort}}` wird bei jeder Anzeige neu erzeugt und **nirgends
gespeichert**. Sobald sich die Seite neu aufbaut — auch nach dem Speichern eines Schritts — steht dort
ein anderes. Auf dem Ausdruck steht `[Passwort – nicht gespeichert]`.

**Was tun:** Es gibt keinen Weg, es nachzuschlagen; es existiert nicht mehr. Setz im Zielsystem ein
neues Passwort und gib es weiter. Beim nächsten Mal: **kopieren und sofort weiterreichen**, bevor du
etwas anderes anklickst. Meldet der Streifen oben „Beim Neuladen entsteht ein neues Passwort“,
kopiere das angezeigte erst.

## Ein Gerät lässt sich nicht löschen

**Ursache:** an dem Gerät hängt mindestens ein Lauf — die Meldung nennt die Zahl. Ein Lauf muss für
immer nachvollziehbar bleiben. Oder deine Rolle ist nicht **Administrator**; nur er sieht den Knopf.

**Was tun:** **archivieren** statt löschen. Das Gerät verschwindet aus allen Auswahllisten und nimmt
keine neue Arbeit an, bleibt aber in jeder Historie — und lässt sich mit **wieder freigeben**
zurückholen.

Und bedenke: eine echte Löschung **verbrennt den Tag-Code für immer**. Ein schon gedruckter Aufkleber
dieses Codes ist danach wertlos.

## Eine Vorlage steht nicht zur Wahl

**Ursache:** eine von vier, in dieser Reihenfolge zu prüfen:

1. Sie hat **keine veröffentlichte Version** — ein Entwurf ist noch niemandes Arbeitsanweisung.
2. Sie ist **archiviert**.
3. Sie gehört **einem anderen Kunden** („nur Musterfirma GmbH“).
4. Auf der Geräteseite: sie verlangt **Pflichtangaben**. Dann steht sie mit dem Zusatz „fragt noch
   nach Angaben“ dabei und führt in den Start-Dialog, statt sofort zu starten — hier wird ja niemand
   gefragt.

**Was tun:** Fall 1 und 2 löst ein Redakteur auf der Vorlagenseite (**Veröffentlichen**
beziehungsweise **wieder freigeben**), Fall 3 ein Administrator über die Kundenzuordnung in den
Kopfdaten. Fall 4 ist kein Fehler: nimm den Start-Dialog.

## Ein Lauf oder ein Gerät ist nicht auffindbar

**Ursache und was tun:**

- **Die Liste ist gekappt.** Die Laufliste zeigt höchstens 200 Läufe, die Archivsuche höchstens 100
  Treffer, die Gerätehistorie die letzten 20. Steht das dabei, such genauer statt zu blättern:
  Titel, Ticket, Hostname, Person oder Tag-Code.
- **Der Lauf ist archiviert.** Archivierte Läufe stehen **nicht** in der Laufliste. Nimm das
  **Archiv** — dort auch das Häkchen **auch offene und laufende Läufe**, wenn du beides zugleich
  suchst.
- **Die Person ist deaktiviert.** Setz in der Personenliste das Häkchen **auch deaktivierte**.
- **Das Gerät ist archiviert.** Setz in der Geräteliste das Häkchen **auch archivierte**.
- **Es gehört einem anderen Kunden.** Dann ist es für dich nicht vorhanden, und daran ändert auch ein
  weitergegebener Link nichts.