Bleiben Dokumente im Consume-Ordner von Paperless-ngx liegen, liegt die Ursache häufig bei der Ordnerzuordnung, den Zugriffsrechten oder der Importverarbeitung im Container. Das allein ist noch kein Hinweis auf einen RAID- oder Laufwerksdefekt; ungesicherte Eingangsdateien solltest du trotzdem außerhalb des überwachten Ordners sichern. Sichere zuerst Containerstatus, Protokolle und die verwendete Konfiguration, bevor du mit einer einzelnen Testdatei die Verarbeitung prüfst. Lösche vorerst weder Container-Volumes noch Datenbankinhalte und starte keine Neuinstallation.
Den Importweg mit einer einzelnen Datei eingrenzen
Paperless-ngx muss eine Datei zunächst im überwachten Verzeichnis erkennen, einen Verarbeitungsauftrag anstoßen und das Dokument anschließend verarbeiten und speichern. Ein laufender Webzugang bestätigt nur einen Teil dieser Kette. Auch ein als gestartet angezeigter Container beweist nicht, dass Consumer und Aufgabenverarbeitung funktionieren.
Notiere die installierte Paperless-ngx-Version sowie das verwendete Container-Image einschließlich Tag. Prüfe in der Containerverwaltung deines NAS die Laufzeit, Neustarts und Protokolle des Paperless-Dienstes sowie der zugehörigen Datenbank- und Redis-Dienste. Nutzt deine Installation getrennte Prozesse oder Container für Consumer und Worker, müssen auch deren Protokolle berücksichtigt werden. Die offizielle Paperless-ngx-Dokumentation bietet unter Configuration die passenden Variablenbeschreibungen; gleiche diese mit deiner installierten Version ab.
- Pausiere Scanner und andere automatische Zulieferer. Kopiere die wartenden Originaldateien zur Sicherung in einen nicht überwachten Ordner, ohne sie zunächst aus dem Consume-Ordner zu löschen.
- Verwende eine kleine, unverschlüsselte PDF-Datei, deren Inhalt noch nicht in Paperless-ngx vorhanden ist. Kopiere sie vollständig in die oberste Ebene des Consume-Ordners und notiere Uhrzeit und Dateinamen.
- Beobachte die Import- beziehungsweise Aufgabenansicht, soweit in deiner Version vorhanden, und die Containerprotokolle. Suche nach dem Dateinamen und nach Meldungen zur Dateierkennung, Aufgabenannahme oder Verarbeitung.
- Falls keinerlei Erkennung sichtbar wird, lade dieselbe Datei einmal über die Weboberfläche hoch. Prüfe danach erneut die Aufgaben und Protokolle.
Funktioniert der Webupload, aber der Ordnerimport erzeugt keinen Auftrag, konzentriere dich auf Mount, Überwachung und Rechte des Consume-Ordners. Scheitern beide Wege vor oder während der Verarbeitung, sind Worker, Redis, Datenbank oder gemeinsame Speicherziele zu prüfen. Wird nur diese eine Datei abgewiesen, während andere Dokumente funktionieren, führt der Weg zur dateibezogenen Diagnose.
Ein erfolgreicher Upload kann das Testdokument bereits angelegt haben. Ein späterer Import derselben Datei kann dann als Duplikat enden. Diese Rückmeldung ist für den Test verwertbar und nicht automatisch ein neuer Fehler.
Sieht der Container denselben Ordner wie dein NAS?
Der im NAS-Dateimanager sichtbare Eingangsordner und das von Paperless-ngx überwachte Verzeichnis müssen über einen Mount miteinander verbunden sein. Ein gleichlautender Ordnername reicht nicht aus: Der Container besitzt einen eigenen Verzeichnisbaum.
Prüfe in den eingebundenen Ordnern oder in der Projektkonfiguration die Quellseite auf dem NAS und die Zielseite im Container. Bei einer üblichen Docker-Installation liegt das Consume-Ziel unter /usr/src/paperless/consume. Entscheidend ist jedoch der tatsächlich verwendete Wert von PAPERLESS_CONSUMPTION_DIR beziehungsweise dessen Standardwert in deiner Installation.
Ein möglicher Fehlerfall: Der Scanner speichert in den NAS-Ordner Dokumenteneingang, während der Container einen anderen, ebenfalls vorhandenen Ordner als Consume-Verzeichnis einbindet. Paperless-ngx arbeitet dann korrekt, sieht aber die erwarteten Dateien nicht.
Öffne über die Containerverwaltung eine Verzeichnisansicht oder eine geeignete Containerkonsole und kontrolliere rein lesend, ob die Testdatei am internen Consume-Pfad vorhanden ist. Vergleiche Dateiname und Größe mit der Datei auf dem NAS. Fehlt sie dort, korrigiere zuerst die Ordnerzuordnung; OCR-Einstellungen können diesen Fehler nicht beheben.
Liegt die Datei in einem Unterordner, prüfe außerdem PAPERLESS_CONSUMER_RECURSIVE. Ohne aktivierte rekursive Überwachung werden Unterordner nicht wie die oberste Ebene behandelt. Verschachtelte Scannerablagen können dadurch unbemerkt außerhalb des vorgesehenen Importwegs liegen.
Lesen reicht nicht: Rechte für den gesamten Import prüfen
Ein erfolgreicher Zugriff über SMB bestätigt nicht die Rechte des Paperless-Prozesses. Dein angemeldeter NAS-Benutzer und der Benutzer innerhalb des Containers können unterschiedliche Identitäten und Berechtigungen besitzen.
Für den üblichen Consume-Ablauf muss Paperless-ngx Verzeichnisse betreten, Dateien lesen und nach erfolgreicher Verarbeitung die Eingangsdatei entfernen können. Zusätzlich benötigt die Anwendung passende Schreibrechte für ihre Daten- und Medienverzeichnisse. Ein als schreibgeschützt eingebundener Consume-Ordner passt deshalb nicht zum normalen Ablauf.
Bei Nutzung des offiziellen Docker-Images sind USERMAP_UID und USERMAP_GID relevante Prüfpunkte. Sie dienen der Zuordnung zur Benutzer- und Gruppenkennung auf dem Host. Prüfe die wirksamen Werte und die zugehörigen NAS-Rechte, statt eine beliebige Benutzerkennung aus einer fremden Anleitung zu übernehmen.
- Fehler beim Öffnen der Eingangsdatei sprechen für fehlende Leserechte oder fehlende Verzeichnisrechte auf dem Weg zur Datei.
- Fehler beim Entfernen der Eingangsdatei lenken den Blick auf Schreib- und Löschrechte im Consume-Verzeichnis sowie auf den Schreibschutz des Mounts.
- Fehler beim Speichern des Originals oder der erzeugten Dateien betreffen eher Medienverzeichnis, Datenverzeichnis, Speicherplatz oder Quoten.
NAS-ACLs können zusätzlich zu klassischen Linux-Rechten wirken. Eine sichtbare Eigentümerzuordnung allein beweist daher keinen ausreichenden Zugriff. Teste erforderliche Schreibrechte nur in den vorgesehenen Anwendungsordnern mit einer entbehrlichen Datei und unter der Identität des Anwendungsprozesses. Ein Test als root kann fehlende Rechte verdecken.
Setze nicht pauschal alle Freigaben auf Vollzugriff und starte den Container nicht dauerhaft mit erhöhten Rechten. Begrenze Änderungen auf das betroffene Verzeichnis und dokumentiere die bisherigen Einstellungen für den Rückweg.
Datei vorhanden, aber keine Erkennung: Überwachung und Polling
Sieht der Container die Datei, ohne dass Paperless-ngx einen Import anstößt, ist die Verzeichnisüberwachung ein eigener Prüfzweig. Besonders bei über SMB oder NFS eingebundenen Verzeichnissen können Dateisystemereignisse fehlen oder nicht so ankommen, wie die Anwendung sie erwartet.
Die Einstellung PAPERLESS_CONSUMER_POLLING aktiviert eine regelmäßige Prüfung des Consume-Verzeichnisses. Der Wert bezeichnet das Prüfintervall in Sekunden. Ein beispielhafter Testwert von 10 bedeutet eine Prüfung im Abstand von zehn Sekunden; er ist keine Zusage, dass ein Dokument nach zehn Sekunden fertig verarbeitet ist.
Trage den Wert in der bestehenden Umgebungskonfiguration des Paperless-Dienstes ein. Halte den bisherigen Zustand fest und übernimm die Änderung über den Aktualisierungs- oder Neuerstellungsweg deiner Containerverwaltung. Ein bloßer Neustart übernimmt geänderte Umgebungsvariablen nicht in jedem Bereitstellungsweg. Lösche dabei keine persistenten Daten und wähle keinen Vorgang, der Volumes entfernt.
Kontrolliere danach die wirksame Containerkonfiguration und beobachte einen frischen Testimport über mehrere Prüfintervalle. Beginnt die Erkennung erst mit Polling, deutet das auf die bisherige Ereignisüberwachung oder die Eigenschaften des eingebundenen Dateisystems hin. Bleibt sie aus, prüfe den Start des Consumers und den tatsächlich überwachten Pfad erneut anhand seiner Protokolle.
Ein Scanner darf währenddessen keine noch unvollständige Datei zur Verarbeitung anbieten. Beobachte, ob die Dateigröße weiter wächst oder die Übertragung noch läuft. Wenn die Scannerfunktion es unterstützt, ist eine vollständig abgeschlossene Ablage mit anschließendem Verschieben innerhalb desselben Dateisystems sinnvoll. Dateistabilitäts- und Warteeinstellungen solltest du versionsbezogen in der Consumer-Konfiguration prüfen, statt Prüfintervalle wahllos zu verkürzen.
Auftrag vorhanden, aber Dokument wird nicht fertig
Ein erkannter oder eingereihter Auftrag verschiebt die Diagnose von der Ordnerüberwachung zur Verarbeitung. Redis vermittelt Aufgaben in der üblichen Paperless-ngx-Architektur; Worker führen die Verarbeitung aus. Die erreichbare Weboberfläche schließt Fehler in diesen Komponenten nicht aus.
Suche zum Testzeitpunkt nach Verbindungsfehlern zu Redis oder zur Datenbank, nach wiederholten Worker-Neustarts und nach Abbrüchen während der OCR. Prüfe dabei die Dienste aus deinem eigenen Projekt. Dienstnamen, Zugangsdaten und Netzwerke aus einer anderen Compose-Konfiguration lassen sich nicht ungeprüft übertragen.
Eine wachsende Warteschlange ohne beginnende Bearbeitung lenkt den Verdacht auf Worker oder Aufgabenvermittlung. Beginnt die Verarbeitung und endet erst bei OCR oder beim Speichern, ist die letzte erfolgreiche Phase der bessere Ansatzpunkt. Lösche weder Redis-Daten noch die Aufgabenwarteschlange auf Verdacht; dadurch können Diagnoseinformationen und wartende Aufträge verloren gehen.
Prüfe außerdem freien Platz und Quoten für Consume-, Medien- und Datenverzeichnisse sowie den für temporäre Verarbeitung verfügbaren Speicher. Freier Platz auf dem NAS insgesamt genügt nicht, wenn ein einzelnes Volume oder eine Containerquote ausgeschöpft ist. Wiederholte Containerabbrüche können auch mit Speichermangel zusammenhängen; kontrolliere dafür die Ressourcenanzeige und die Ereignisse der Containerlaufzeit.
Meldet das NAS gleichzeitig ein schreibgeschütztes Volume, Ein-/Ausgabefehler oder einen beeinträchtigten Speicherpool, stoppe weitere Importversuche. Dann hat die Sicherung der vorhandenen Dokumente und die Prüfung der Speicherebene Vorrang. Eine RAID-Reparatur ist keine Maßnahme zur Behebung eines Paperless-Importfehlers.
Nur einzelne Dokumente bleiben liegen
Scheitern bestimmte Dateien bei ansonsten funktionierendem Import, prüfe Dateiinhalte und Importmeldungen. Ein geänderter Dateiname beseitigt weder eine Beschädigung noch einen inhaltlich erkannten Doppelimport.
- Duplikatmeldung: Suche das vorhandene Dokument in Paperless-ngx und prüfe, ob es vollständig geöffnet werden kann. Das Verbleiben beziehungsweise Entfernen abgewiesener Duplikate hängt von der passenden Consumer-Konfiguration ab; aktiviere automatisches Löschen erst nach gesicherter Kontrolle.
- Verschlüsselte oder beschädigte PDF-Datei: Öffne eine gesicherte Kopie außerhalb von Paperless-ngx. Erstelle gegebenenfalls eine neue unverschlüsselte Exportdatei, ohne das Original zu überschreiben.
- Nicht unterstütztes Format: Vergleiche den tatsächlichen Dateityp mit den unterstützten Formaten und den Anforderungen deiner Installation. Office-Dokumente können zusätzliche Konvertierungsdienste wie Tika und Gotenberg benötigen; ein funktionierender PDF-Import bestätigt diese Dienste nicht.
- OCR-Abbruch: Prüfe die Fehlermeldung auf Sprachdaten, Ressourcenprobleme oder beschädigte Seiten. Ein schlecht lesbarer Scan allein erklärt nicht jeden technischen OCR-Abbruch.
- Temporäre oder versteckte Datei: Scanner und Kopierprogramme können Begleitdateien erzeugen. Prüfe die Ausschlussregeln des Consumers und teste mit einer regulären PDF-Datei ohne temporäre Endung.
Vermeide wiederholte Massenimporte desselben Bestands. Eine unveränderte Fehlerdatei wird durch erneutes Kopieren meist nicht repariert und kann die Warteschlange unnötig belasten.
Den behobenen Import bis zum Dokument prüfen
Die Reparatur ist erst bestätigt, wenn ein neues Testdokument vollständig in Paperless-ngx angekommen ist. Das Verschwinden aus dem Consume-Ordner allein genügt nicht: Prüfe, ob das Dokument in der Weboberfläche erscheint, sich öffnen lässt und das Original heruntergeladen werden kann. Kontrolliere bei einem Scan zusätzlich, ob die erwartete Texterkennung funktioniert.
Teste danach eine weitere Datei über den tatsächlichen Zulieferweg, also beispielsweise über den Scanner statt nur über eine manuelle Kopie. So werden abweichende Dateirechte und Übertragungsverhalten sichtbar. Gib den wartenden Bestand anschließend in überschaubaren Teilmengen frei und behalte Fehlerprotokolle und Ressourcen im Blick.
Bleibt die Ursache offen, halte für eine gezielte Supportanfrage Paperless-ngx-Version, Image-Tag, bereinigte Mount- und Umgebungskonfiguration, Zeitpunkt des Testimports und die zugehörigen Protokollzeilen bereit. Entferne Passwörter, Schlüssel und vertrauliche Dokumentinhalte. Diese Informationen grenzen den ausgefallenen Verarbeitungsschritt besser ein als eine Neuinstallation ohne Befund.