Fehlerbehebung

Zuerst immer die Installationsprüfung ausführen:

cd backend
..\runtime\python\python.exe -m app.cli check    # Windows
../runtime/python/bin/python3 -m app.cli check   # Linux

Exit-Code 0 bedeutet betriebsbereit, 1 ein blockierendes Problem. Die Ausgabe nennt Konfiguration, Datenverzeichnis, Datenbankrevision, Port, imapsync und Frontend-Build.

Port belegt oder gesperrt

Symptom: Start endet mit Exit 3 oder WinError 10013. Unter Windows kann ein Port per Richtlinie gesperrt sein, obwohl kein Prozess ihn nutzt.

Lösung: Laufende Instanz beenden (sonst Exit 4) oder einen festen Port setzen, damit die OAuth-Redirect-URI stabil bleibt:

APP_PORT=8010
APP_BASE_URL=http://127.0.0.1:8010

Danach die Redirect-URI in Entra auf denselben Port ändern. Der Ausweichbereich endet bei 8025; ist keiner frei, startet die Anwendung nicht. Belegende Prozesse zeigt netstat -ano | findstr :8000 (Windows) bzw. ss -ltnp | grep :8000 (Linux).

Laufzeit fehlt oder ist unvollständig

Symptom: [Fehler] Portable Laufzeit ist unvollständig (Perl, imapsync) oder runtime\python\python.exe fehlt.

runtime\python\python.exe scripts\provision_runtime.py --check
start.bat --repair

./start.sh --repair

Das richtet runtime/python, runtime/perl und runtime/imapsync neu ein; Daten und .env bleiben erhalten. Voraussetzung ist Internetzugang. Schlägt der Download fehl, Prüfsummen im Setup-Protokoll kontrollieren und runtime/.cache bei Bedarf leeren.

imapsync fehlt oder ist inkompatibel

Symptom: imapsync_unavailable oder imapsync_incompatible.

runtime\perl\perl\bin\perl.exe runtime\imapsync\imapsync --version
runtime\perl\perl\bin\perl.exe runtime\imapsync\imapsync --help | findstr /C:"--oauthaccesstoken1" /C:"--passfile2"

Erwartet wird 2.326 und beide Optionen. Fehlt das Skript, setup.bat ausführen; fehlt Perl, start.bat --repair. Ein imapsync im System-PATH wird bewusst ignoriert; ein abweichender Pfad muss explizit gesetzt werden:

IMAPSYNC_PATH=runtime/imapsync/imapsync

TLS-Fehler

Symptom: Exit-Code 12 (imapsync_tls) oder Zertifikatsfehler im Test.

openssl s_client -connect mail.example.org:993 -servername mail.example.org

Verify return code: 0 (ok) bedeutet in Ordnung; self-signed certificate ein nicht vertrauenswürdiges Zertifikat; no peer certificate available einen falschen Port oder fehlendes TLS. Der Hostname muss zum Zertifikat passen (CN/SAN), Zugriff über IP scheitert an der Namensprüfung. Port prüfen (993 implizit, 143 STARTTLS), eigene CA in den Systemtrust aufnehmen. Die TLS-Prüfung lässt sich nicht abschalten.

Anmeldefehler an der Quelle

Symptom: Exit-Code 161 oder reauth_required.

Kontostatus unter „Microsoft 365“ prüfen: connected oder reauth_required.
IMAP am Postfach aktiv? In Exchange Online:

Get-CASMailbox -Identity user@contoso.com | Select-Object ImapEnabled
Set-CASMailbox -Identity user@contoso.com -ImapEnabled $true

Quelle und Ziel testen, ohne Mails zu verändern:

curl -X POST http://127.0.0.1:8000/api/v1/jobs/<job-id>/test \
  -H "X-CSRF-Token: <csrf-token>" -b cookies.txt

Bei reauth_required das Konto erneut autorisieren. Wurde die Zustimmung entzogen, Administratorzustimmung in Entra erneuern. Blockiert Conditional Access den Login, die Richtlinie prüfen — die Anmeldung erfolgt im Browser.

Anmeldefehler am Ziel

Symptom: Exit-Code 162 (imapsync_auth_target). Zieladresse exakt wie am Zielserver? Passwort am Job oder als Standard am Zielserver hinterlegt? Der Ziel-Test lässt sich in der Oberfläche unter „Zielserver“ auslösen oder per POST /api/v1/targets/{id}/test mit Benutzername und Passwort im Request-Body; beides prüft nur den Login. Passwort korrigieren (ohne Passwortfeld bleibt der gespeicherte Wert erhalten) und prüfen, ob der Zielserver den Login erlaubt. Bei Mailcow/Dovecot muss der Benutzer existieren und IMAP freigeschaltet sein.

Datenbank gesperrt

Symptom: 503 database_busy mit Retry-After. SQLite erlaubt nur einen Schreiber; zwei Instanzen oder ein laufendes Update erzeugen Sperren. Die Sperrdatei enthält die PID (type data\queue.lock bzw. cat data/queue.lock); mit tasklist /FI "PID eq <pid>" bzw. ps -p <pid> -o pid,cmd prüfen, ob der Prozess noch lebt. Läuft eine zweite Instanz, beenden. Pro Datenverzeichnis ist genau eine zulässig; eine veraltete Sperrdatei wird beim Start ersetzt. Bei wiederholtem 503 die Anwendung neu starten und die Anfrage erneut senden.

Weitere Fälle

Fall	Ursache	Abhilfe
Exit 4	zweite Instanz	laufende Instanz nutzen oder beenden
Passwort vergessen	kein Standardpasswort	`python -m app.cli set-password` (verdeckte Eingabe)
nur JSON, leere Seite	`frontend/dist` fehlt	vollständiges Release oder `npm ci && npm run build`
`folder_preview_failed`	Verbindung oder Rechte	Quelle testen, Kontostatus prüfen
`[log truncated…]`	5-MB-Grenze	`RUN_LOG_MAX_BYTES` erhöhen, neu starten

set-password wird aus backend\ mit ..\runtime\python\python.exe bzw. ../runtime/python/bin/python3 aufgerufen; ein Neustart ist nicht nötig.

Update schlägt fehl

Meldung	Ursache	Abhilfe
`application_running`	Anwendung läuft	beenden, erneut starten
`migrations_running`	Lauf aktiv	abwarten oder abbrechen
`auth_required`	privates Repository ohne Token	`FORGEJO_TOKEN` setzen
`invalid_signature`	Release manipuliert	Release prüfen; nichts wurde geändert
`unsigned_release`	Signatur fehlt	anderes Release verwenden
`migration_failed`	DB-Migration fehlgeschlagen	Installation wurde zurückgerollt

Die Sicherung liegt unter data/updates/backup-<Zeitstempel>/. Für eine Fehlermeldung sammeln: Ausgabe von python -m app.cli check, Version aus VERSION und Plattform, betroffener Lauf mit Exit-Code und Fehlercode, letzte Zeilen des redigierten Protokolls sowie die Angabe, ob der Fehler mit IMAP-Quelle oder Microsoft 365 auftritt. Keine Tokens, Passwörter oder vollständigen .env-Inhalte weitergeben.