Fehlersuche und Support

Alles dazu steht in der Werkbank unter Wartung und Fehlersuche. Die Gruppe enthält Systemzustand, Protokoll, Gemeldete Fehler, Wartungsmodus, Wartungsoperationen und Demo-Daten. Diese Seite beschreibt die Werkzeuge zur Fehlersuche und die Technik (Version und Updates), die unter Einstellungen steht; Systemzustand, Wartungsmodus, Wartungsoperationen und Demo-Daten haben eigene Seiten. Sicherung, Wiederherstellen und Vollexport stehen unter Daten sichern.

Protokoll und Gemeldete Fehler gehören zur Vorlage Betrieb. Technik steht in jeder Vorlage.

Einen Bereich nicht in der Leiste gefunden?

Manche Bereiche der Werkbank, zum Beispiel Wartungsmodus, Datenbank-Anbindung oder Wartungsoperationen, sind in der Vorlage Haushalt ausgeblendet. Unten in der Leiste steht, wie viele Bereiche ausgeblendet sind; ein Klick zeigt sie. Dauerhaft einblenden kannst du sie unter Werkbank anpassen. Ausgeblendet heißt nicht abgeschaltet.

Gemeldete Fehler

Benutzer melden Fehler über Fehler melden in ihrem Menü – mit eigener Beschreibung, bis zu zwei Screenshots und technischen Angaben (Version, Browser, Bildschirmgröße, Sprache, Zeitzone, die letzten 25 besuchten Seiten, die letzten 10 Fehler im Browser und fehlgeschlagenen Anfragen). Passwörter, Inhalte von Mappen und Cookies gehen nicht mit. Die Meldung bleibt in deinem Ablago – sie geht nie an das Projekt. Wer daraus ein GitHub-Issue machen will, tut das selbst.

Unter Werkbank → Gemeldete Fehler stehen die Meldungen, neueste zuerst; der Zähler in der Leiste und in der Übersicht nennt die offenen. In der Meldung siehst du Beschreibung, Screenshots und Angaben und kannst sie als erledigt markieren (und wieder öffnen) oder löschen – endgültig, samt Bildern. Eine Rückmeldung an den Benutzer gibt es in Ablago bewusst nicht; die erledigst du auf deinem Weg.

Protokoll

Werkbank → Protokoll zeigt, was in Ablago passiert – die letzten 24 Stunden, höchstens 10.000 Einträge, die neuesten oben. Nach einem Neustart beginnt die Liste leer; dauerhaft steht alles in den Container-Logs.

Jeder Eintrag gehört zu einem Modul, etwa konto für Anmeldungen oder sicherung für Sicherungen. Welche Module es gibt, steht unter Technik → Module.

Filtern lässt sich nach Stufe, Modul, Benutzer und Text; Live aktualisiert die Liste alle zwei Sekunden. Ein Klick auf einen Eintrag zeigt alle Daten dazu, auch Benutzer und Anfrage-Kennung.

Debug-Modus

Schaltet für eine Stunde zusätzliche, ausführliche Meldungen ein – etwa jede einzelne Datenbankabfrage. Danach (oder nach einem Neustart) ist er von selbst wieder aus. Die Grundstufe stellt LOG_LEVEL ein (siehe Installation).

Container-Logs

Jede Meldung steht als lesbare Zeile in den Logs des Containers:

2026-10-28T09:12:33.120Z INFO  [ablage] Mappe angelegt benutzer=lena@example.org typ=Rechnung titel="R-17 vom 01.10.2026"

docker logs <app-container>

Datenbank

Lange Datenbankzugriffe und Anfragen, die Auslastung des Servers und was gerade in der Datenbank läuft stehen unter Werkbank → Einstellungen → Datenbank-Anbindung, unter der Verbindung – siehe Lange Datenbankzugriffe. Wirkt Ablago langsam, schau dort zuerst nach – und unter Wartung und Fehlersuche → Systemzustand, wie ausgelastet CPU, Arbeitsspeicher und Netzwerk sind.

Einträge, die mit Anfrage: beginnen, betreffen eine ganze Anfrage; aufgeklappt zeigen sie die Aufteilung: Warten vor dem Handler, Datenbank (mit Anzahl der Zugriffe), Rechte, Aufbereitung und JSON. Einzelheiten zur selben Zeit stehen im Protokoll (Modul datenbank).

Auslastung des Servers: Ablago arbeitet Anfragen auf einem Faden ab. Rechnet eine Anfrage lange, warten alle anderen so lange. Die Werte zeigen, wie lange in der letzten Minute üblicherweise, in 99 % der Fälle und höchstens gewartet wurde. Unter 50 ms ist unauffällig; ab 100 ms (99 %) erscheint ein Hinweis.

Zeitmessung (Entwicklermodus)

Wirkt eine Seite langsam, schalte im Profil den Entwicklermodus ein. Dann zeigt Ablago unten rechts bei jedem Seitenaufruf je Anfrage, wo die Zeit geblieben ist, oben die Summe über alle Anfragen der Seite. Er gilt nur für dein Konto.

Abschnitt	Was es ist
Warten (Browser)	Die Anfrage wartet im Browser. Er schickt höchstens etwa 6 Anfragen gleichzeitig an einen Server, die übrigen warten.
Leitung	Hin- und Rückweg ohne die Zeit im Server – eine Näherung. Sie enthält auch das Warten, bevor der Server die Anfrage überhaupt annimmt; ist er beschäftigt, zeigt das die Auslastung unter Werkbank → Datenbank.
Warten (Server)	Vom Eingang im Server bis zur Bearbeitung, z. B. Körper der Anfrage lesen.
Rechte	Berechtigungen auswerten (Zugriff bilden, Lesefilter, Rechte je Mappe), ohne die Datenbankzugriffe darin.
Datenbank	Anzahl und Dauer der Datenbankzugriffe.
Aufbereitung	Die übrige Zeit im Server.
JSON	Die Antwort im Server in Text umwandeln.
Übertragung, Auswerten, Darstellung	Antwort senden, im Browser lesen und zeichnen.

Die Werte kommen vom Server im Header Server-Timing (vor, app, db, rechte, json, gesamt) und aus der Zeitmessung des Browsers. Bei den Zahlen der Ansichten (/api/sichten) steht dort zusätzlich zs: treffer, wenn sie aus dem Zwischenspeicher kamen, neu, wenn sie gezählt wurden – gezählt wird nach jeder Änderung im Haushalt, sonst spätestens nach 5 Minuten (Ansichten mit Datumsbezug) bzw. 30 Minuten und um Mitternacht.

Technik

Werkbank → Einstellungen → Technik zeigt im Abschnitt Installiert (unter Neuere Versionen), was installiert ist: Version und Stand von Ablago, Laufzeit (Node.js, Betriebssystem), Datenbank, Bibliotheken und Oberfläche.

• Für den Support: Übersicht kopieren und in ein GitHub-Issue einfügen. Passwörter und Zugangsdaten stehen nicht darin.
• Neuere Versionen: Ein Knopfdruck fragt nach, ob es neuere Versionen gibt – bei GitHub für Ablago, bei endoflife.date für Node.js, PostgreSQL und Alpine, bei npm für die Bibliotheken. Ohne Knopfdruck fragt Ablago nirgends nach. Bei Ablago selbst steht unter Aktuell das neueste Release mit Datum; liegen auf main schon weitere Änderungen, die noch in keinem Release sind, nennt sie der Hinweis.

Wie die Bausteine zusammenhängen, beschreibt Technik.

Typische Probleme

Nach dem Update startet der Container nicht.

Im Container-Log steht der Grund, meist eine Migration oder eine fehlende Datenbankverbindung. Die Migrationen laufen in einer Transaktion – die Datenbank ist dabei unverändert geblieben. Notfalls auf die vorherige Version zurück (Image-Tag) und ein Issue mit dem Log anlegen.

E-Mails kommen nicht an.

Unter Werkbank → E-Mail und Adresse zuerst Verbindung prüfen, dann Testmail senden – darunter steht die Meldung des Mailservers. Typisch: falsches Passwort (bei vielen Anbietern braucht es ein App-Passwort), Verbindungsart passt nicht zum Port (STARTTLS ↔ 587, SSL/TLS ↔ 465), Port vom Netz gesperrt. Im Protokoll (Modul mail) steht jeder Versand mit Fehler. Auch im Spam-Ordner nachsehen.

Ablago ist zäh, während jemand exportiert oder viele PDFs bearbeitet.

Schwere Arbeiten laufen in eigenen Arbeitern (#542); andere Benutzer sollten davon kaum etwas merken. Unter Werkbank → Systemzustand → Auslastung siehst du, ob die Arbeiter beschäftigt sind, wie viele Aufträge warten und wie hoch die Wartezeit des Servers ist. Ist die CPU des Containers dauerhaft am Anschlag, fehlen Kerne – gib dem Container mehr (cpus:) oder setze DMS_ARBEITER niedriger, damit Anfragen und Datenbank mehr Rechenzeit bekommen. Steht im Protokoll „Hohe Wartezeit des Servers“, obwohl die Arbeiter nichts tun, rechnet etwas im Hauptfaden: Bitte als Issue melden, mit dem Protokolleintrag.

Eine PDF-Bearbeitung oder ein Export bricht mit „dauerte länger als 10 Minuten“ oder „mehr Arbeitsspeicher als erlaubt“ ab.

Ein Auftrag im Arbeiter darf höchstens 10 Minuten dauern und 1,5 GB Arbeitsspeicher belegen – damit ein einzelnes riesiges PDF Ablago nicht lahmlegt. Exportiere weniger Mappen auf einmal oder teile ein großes PDF vorher („Seiten“). Läuft der Arbeiter an der Grenze des Containers (mem_limit), hilft mehr Arbeitsspeicher für den Container.

Links in E-Mails zeigen auf localhost.

Unter Werkbank → E-Mail und Adresse die Adresse eintragen, unter der Benutzer Ablago aufrufen.

Anmeldung klappt hinter dem Proxy nicht.

Ist die Adresse von Ablago (Werkbank → E-Mail und Adresse) eine https://-Adresse, wird das Sitzungs-Cookie nur über HTTPS gesetzt. Rufe Ablago dann auch über HTTPS auf. Steht TRUST_PROXY auf false oder auf einer Liste, die den Proxy nicht enthält, glaubt Ablago dem Proxy nicht, dass die Verbindung HTTPS ist – dann die Variable entfernen. Siehe Hinter einem Reverse-Proxy.

Im Protokoll und bei den Sitzungen steht immer dieselbe IP-Adresse.

Das ist die Adresse des Reverse-Proxys: Ablago glaubt seinen Angaben nicht. Unter Technik nachsehen, was bei TRUST_PROXY steht. Hat der Proxy eine öffentliche Adresse, kann TRUST_PROXY auf diese Adresse oder auf true gesetzt werden – mehr unter Was der Proxy Ablago mitteilt.

Hochladen großer Dateien bricht ab.

Den Reverse-Proxy größere Anfragen erlauben, z. B. bei nginx client_max_body_size 110m;.

Die Oberfläche ist nach einer Design-Änderung unbedienbar.

?design=standard an die Adresse hängen, siehe Designs.

Ein Benutzer meldet einen Fehler, den ich nicht nachvollziehen kann.

Als dieser Benutzer anmelden und es dort nachstellen.