# Fehlerbehebung

Zuerst das Gesamtbild im Verzeichnis der Installation:

```
./draften status      # Version, Zustand beider Farben der Weboberfläche und der Worker, HTTPS, Datenbanksicherungen
```

Dann genauer:

```
docker compose ps                        # laufen die Dienste, ist die Datenbank gesund?
docker compose logs --tail 50 worker     # die letzten Einträge des Workers
docker compose run --rm worker node diag.mjs mailbox@company.com
```

Der letzte tut dasselbe wie **Verbindung testen** in der Oberfläche: Er nimmt
den für das Postfach gespeicherten Zugriff, holt ein Token, gibt dessen
Berechtigungen aus (nie das Token selbst) und liest den Posteingang.

## Häufige Fehler

| Symptom | Ursache | Was Sie tun |
|---|---|---|
| `set DB_PASSWORD in .env` beim Start | Passwörter der Datenbank fehlen | `.env` ausfüllen |
| `mailbox … has no access yet` | das Postfach hat keine Registrierung und kein verbundenes Konto | Seite des Postfachs → Zugriff auf die Post |
| `Graph … 401 … invalid_client` | falsches oder abgelaufenes Client secret | ein neues Geheimnis bei der Registrierung, dann der Verbindungstest |
| `Graph … 403 … AppOnly AccessPolicy` | die Application Access Policy wirkt noch nicht, oder das Postfach ist nicht in der Gruppe | warten (auch Stunden), den Test wiederholen; das Postfach in die Gruppe aufnehmen |
| `Graph … 403 … ErrorAccessDenied` | die Administratorzustimmung fehlt | in Entra bei der Registrierung Grant admin consent |
| `Category not added … MailboxSettings` | die Berechtigung `MailboxSettings.ReadWrite` fehlt; die Markierung funktioniert, nur ohne Farbe | die Berechtigung hinzufügen und zustimmen |
| `No active assistant in the database` | der Assistent ist ausgeschaltet, oder die Anfangsdaten wurden nicht eingerichtet | den Assistenten einschalten; das Startlog prüfen |
| der Assistent wird übersprungen („no prompts yet“) | der Assistent hat keine geschriebenen Anweisungen | die Einrichtung abschließen oder die Anweisungen selbst schreiben |
| `Draft without signature` / `links outside the allowed domains` | der Entwurf hat eine Prüfung nicht bestanden | die Nachricht ansehen – es kann ein Täuschungsversuch sein |
| `Limit reached` | das Tageslimit oder das Limit pro Absender | nur erhöhen, wenn die Flut von Post legitim ist |
| `Model refused to answer` | der Sicherheitsfilter des Modells | die Nachricht von Hand bearbeiten |
| `Model exhausted max_iterations` | das Modell hat sich in seinen Werkzeugen verfangen | zweimal wiederholt; kommt es immer wieder, die Anweisung Aufgabe abstimmen |
| `ECONNREFUSED … 3306` | die Datenbank ist nicht erreichbar oder noch nicht hochgefahren | `docker compose ps`, `docker compose logs db` |
| die Leiste „Die Lizenz ist abgelaufen“ oder „Die Installation hat keine Lizenz“, die Assistenten schreiben nichts | die Lizenz fehlt oder ist abgelaufen | eine gültige Lizenz hochladen – siehe [Die Lizenz](/de/admin/licence) |
| eine Aktualisierung endete mit einem Fehler | die neue Version wurde nicht gesund; die vorherige bedient weiter | der Fehler unter Aufträge oder in der Ausgabe von `./draften update`; `./draften status` |
| „Die letzte tägliche Sicherung ist fehlgeschlagen“ in der Karte Datenbanksicherungen | die Datenbanksicherung ist fehlgeschlagen (die Meldung steht in der Karte); eine Stunde später wird sie erneut versucht | `./draften backup` ausführen und den Fehler lesen; den freien Speicherplatz prüfen (`df -h`) und `./draften status` |

## Wenn das Log es nicht zeigt

- Die Oberfläche: Einstellungen des Assistenten → **Aktivität** (Abrufe der
  Post, Aufträge, Ereignisse) und die Seite **Betrieb** (Worker,
  Warteschlange, Fehler der letzten 24 Stunden).
- Nach drei erfolglosen Versuchen erhält eine Nachricht den Status
  **fehlgeschlagen**; der letzte Fehler steht in ihrer Detailansicht.

## Ein einmaliger Durchgang von Hand

```
docker compose run --rm worker node worker.mjs --dry-run
```

Er nimmt jeden aktiven Assistenten einmal und erzwingt den Probemodus – in die
Post wird nichts geschrieben. Nützlich, um zu prüfen, dass alles funktioniert.

## Wenn Sie unsere Hilfe brauchen

```
./draften diagnose
```

schreibt eine Datei `diagnose-<time>.tar.gz` mit dem Zustand der Installation,
den Versionen, der Konfiguration ohne Geheimnisse und dem Ende der Logs. Senden
Sie sie uns.

!> Schauen Sie in die Datei, bevor Sie sie senden: Die Logs können Adressen und
Betreffzeilen der verarbeiteten Post enthalten. Von selbst verlässt nichts den
Server.