Fehlerbehebung — Hilfe zu draften

Symptom, Ursache und was Sie tun – vom fehlenden Zugriff auf ein Postfach bis zum abgelaufenen Geheimnis.

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
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`

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.