Paperless-NGX Troubleshooting – typische Stolperfallen und schnelle Checks

Selbst gehostetes Paperless-NGX-System mit Dokumentenimport über Scanner, E-Mail und Smartphone

Paperless-ngx läuft, aber importiert keine Dokumente? OCR liefert leere Ergebnisse oder der Consume-Ordner bleibt stumm? Dieser Artikel sammelt die häufigsten Stolperfallen aus der Praxis und zeigt schnelle Checks, mit denen sich typische Fehler bei Docker-, NAS- und NFS-Setups systematisch eingrenzen lassen – kompakt, technisch und Troubleshooting ohne Umwege.

Weitere Artikel zu Paperless-ngx

Paperless startet, aber es erscheinen keine Dokumente im Posteingang

Mögliche Ursachen:

  • falscher oder leerer Consume-Pfad
  • Verzeichnis nicht korrekt gemountet
  • fehlende Schreibrechte für den Container

Checks:

docker compose logs paperless | grep -i consume
docker exec -it paperless ls -l /usr/src/paperless/consume
Code-Sprache: Bash (bash)

➡️ Liegt das Dokument im Container wirklich im Consume-Verzeichnis, nicht nur auf dem Host?

Dokumente werden importiert, aber OCR liefert keinen Text

Mögliche Ursachen:

  • OCR-Sprachen nicht korrekt gesetzt
  • nicht unterstützte Dokumenttypen
  • sehr schlechte Scan-Qualität

Checks:

  • OCR-Sprache prüfen:
PAPERLESS_OCR_LANGUAGE: deu+eng
Code-Sprache: YAML (yaml)
  • Test: PDF mit klar lesbarem Text hochladen und gezielt nach einem Wort suchen

➡️ Paperless selbst läuft, aber OCR arbeitet nur so gut wie die Eingabedaten.

Container laufen, aber Web-UI ist nicht erreichbar

Mögliche Ursachen:

  • Port bereits belegt
  • falsches Port-Mapping
  • Container läuft nicht stabil

Checks:

docker compose ps
docker compose logs paperless
Code-Sprache: Bash (bash)

➡️ Alternativ einen anderen Port testen, z. B. 8080:8000.

PostgreSQL-Fehler oder Paperless verliert Datenbankverbindung

Mögliche Ursachen:

  • Datenbank noch nicht initialisiert
  • Volume beschädigt oder leer
  • Credentials inkonsistent

Checks:

docker compose logs db
docker exec -it paperless-db psql -U paperless -d paperless
Code-Sprache: Bash (bash)

➡️ Wenn nötig: Container sauber stoppen und erneut starten (nicht sofort Volumes löschen).

Paperless läuft, reagiert aber träge oder verzögert

Mögliche Ursachen:

  • zu wenig RAM
  • langsamer Storage
  • OCR auf zu vielen Dokumenten gleichzeitig

Checks:

docker stats
Code-Sprache: Bash (bash)

➡️ Für kleinere Systeme (z. B. NAS oder Raspberry Pi) empfiehlt es sich, große Dokumentenmengen gestaffelt zu importieren.

Dokumente im Consume-Ordner werden nur beim Container-Start verarbeitet (NFS)

Symptom:

  • Dokumente werden nur beim Start des Containers importiert
  • Neue Dateien im Consume-Ordner werden nicht automatisch erkannt

Dieses Verhalten tritt typischerweise auf, wenn der Consume-Ordner über NFS eingebunden ist.

Ursache: Paperless-NGX nutzt standardmäßig Inotify, um Dateisystem-Events zu erkennen.
Bei NFS-Mounts werden diese Events jedoch nicht zuverlässig oder gar nicht an den Container weitergereicht.

Das ist kein Fehler von Paperless, sondern eine technische Einschränkung von NFS in Kombination mit Inotify.

Lösung: Polling für den Consume-Ordner aktivieren

In diesem Fall sollte die Polling-Verarbeitung aktiviert werden.
Paperless prüft dann in regelmäßigen Abständen aktiv, ob neue Dateien im Consume-Ordner liegen.

Einstellung in der docker-compose.yml

environment:
  PAPERLESS_CONSUMER_POLLING: "5"
Code-Sprache: YAML (yaml)

Der Wert gibt das Intervall in Sekunden an, in dem Paperless den Consume-Ordner prüft.

Bewährte Werte aus der Praxis:

  • 5 Sekunden → sehr zuverlässig, minimaler Overhead
  • 10–30 Sekunden → ausreichend für die meisten Setups

Wann ist Polling sinnvoll?

Polling sollte aktiviert werden, wenn:

  • der Consume-Ordner über NFS eingebunden ist
  • externe Systeme (Scanner, Drive, Sync-Tools) Dateien ablegen
  • Import nur beim Container-Start funktioniert

Polling ist kein Workaround, sondern der empfohlene Betriebsmodus für NFS-basierte Consume-Verzeichnisse.

Wann ist Polling nicht nötig?

Polling ist meist nicht erforderlich, wenn:

  • der Consume-Ordner lokal gemountet ist
  • keine Netzwerkdateisysteme im Spiel sind
  • Inotify zuverlässig Events liefert

Fazit zu NFS & Consume-Verarbeitung

Wenn Paperless-NGX mit NFS arbeitet, sollte man nicht erwarten, dass Inotify, also der Event-basiert sofortige Import von Dokumenten im Scan-Ordner zuverlässig funktioniert. Mit der Aktivierung der Polling-Funktion sorgt man in diesem Fall für:

  • deterministisches Verhalten
  • stabile Importe
  • nachvollziehbare Verarbeitung

Gerade in Kombination mit NAS-Systemen ist Polling die robustere und stressfreiere Lösung.

Dokumente werden mehrfach importiert

Mögliche Ursachen:

  • Dokumente bleiben im Consume-Verzeichnis liegen
  • Scanner kopiert statt verschiebt Dateien
  • externer Sync greift parallel ein

Checks:

  • Consume-Verzeichnis nach Import prüfen
  • Scanner-Einstellung auf „Verschieben“ statt „Kopieren“ setzen

➡️ Der Consume-Ordner sollte als reiner Eingang, nicht als Ablage dienen.

Benutzer können sich anmelden, sehen aber keine Dokumente

Mögliche Ursachen:

  • Rechte-/Rollenkonzept nicht korrekt
  • Dokumente sind anderen Benutzern zugeordnet

Checks:

  • Benutzerrollen in den Einstellungen prüfen
  • Testweise Admin-Rechte vergeben

➡️ Paperless ist vollständig multi-user-fähig – Sichtbarkeit ist bewusst steuerbar.

Wann lohnt sich ein kompletter Neustart?

Ein „Neu aufsetzen“ ist meist nicht nötig, wenn:

  • Container sauber starten
  • Logs verständliche Fehler zeigen
  • Datenverzeichnisse intakt sind

Ein Neustart lohnt sich eher bei:

  • fehlerhaften Volumes
  • mehrfachen experimentellen Konfigurationswechseln
  • grundlegender Architekturänderung

Weitere Artikel zu Paperless-ngx

Categories: Technologie
Tags: , , , , , , , , , ,
Michael

Written by:Michael All posts by the author

Ich schreibe und poste hier zu Themen, die mich seit jeher privat als auch beruflich interessieren und begleiten. [Mehr über mich]

You may also like

Search: