Eine kuratierte Liste häufiger Docling-Probleme mit schneller Lösung, empfohlener Lösung und offizieller Quelle. Es werden nur nachvollziehbare Probleme aufgeführt.
Installation unter Windows schlägt fehl
Installation
error: Microsoft Visual C++ 14.0 or greater is required / Failed building wheel for docling-parse
Warum das passiert: Einige optionale Abhängigkeiten kompilieren native C++- oder Rust-Erweiterungen und benötigen einen Compiler, der standardmäßig fehlt.
Schnelle Lösung: Mit Astral uv statt pip installieren, um vorkompilierte Wheels zu nutzen: uv add docling.
Empfohlene Lösung: Wenn Sie pip benötigen, installieren Sie die Microsoft Visual C++ Build Tools (14.0+) und ein 64-Bit-Python und versuchen Sie es erneut. Nutzen Sie auf nicht unterstützten Systemen eine Kombination aus Python 3.10-3.12 oder einen Container.
uv add docling
Wenn das nicht zutrifft: Existiert für Ihr System und Python kein Wheel, kann weiterhin der Compiler-Weg nötig sein.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
Microsoft Visual C++ 14.0 is required. Get it with Microsoft C++ Build Tools
Warum das passiert: pip versucht, eine native Erweiterung aus dem Quellcode zu bauen, und findet die MSVC-Toolchain nicht.
Schnelle Lösung: Bevorzugen Sie uv, das vorkompilierte Wheels auflöst und den Compiler ganz vermeidet.
Empfohlene Lösung: Andernfalls installieren Sie die Build Tools mit der Workload „Desktopentwicklung mit C++“: winget install Microsoft.VisualStudio.2022.BuildTools.
Failed building wheel for docling-parse / ERROR: Failed to build installable wheels for some pyproject.toml based projects
Warum das passiert: Für Ihre Plattform oder Python-Version gibt es kein vorkompiliertes Wheel (z. B. macOS älter als 13, Alpine/Termux, exotische Architekturen oder ein sehr neues Python), daher versucht pip, aus dem Quellcode zu kompilieren.
Schnelle Lösung: Nutzen Sie eine unterstützte Plattform und Python 3.10-3.12 und installieren Sie mit uv, um Wheels zu beziehen.
Empfohlene Lösung: Unter macOS macOS 13+ (Apple Silicon) verwenden; unter Linux eine gängige x86_64/arm64-Distribution oder den offiziellen Container. Fixieren Sie eine Docling-Version, deren Wheels passen, oder bauen Sie mit vollständiger C++-Toolchain.
uv venv --python 3.12 && uv add docling
Wenn das nicht zutrifft: 32-Bit, musl/Alpine ohne Build-Abhängigkeiten und einige ARM-Systeme werden offiziell nicht unterstützt.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
ImportError: libGL.so.1: cannot open shared object file: No such file or directory / ModuleNotFoundError: No module named 'cv2'
Warum das passiert: opencv-python (mit OpenGL-UI) ist in einer headless-Umgebung wie Docker oder einer Remote-VM installiert, oder OpenCV fehlt in einer frischen Umgebung komplett.
Schnelle Lösung: Erzwingen Sie den headless-OpenCV-Build.
Empfohlene Lösung: pip uninstall -y opencv-python opencv-python-headless && pip install --no-cache-dir opencv-python-headless. Alternativ die Systembibliothek installieren: apt-get install libgl1 (Debian) oder dnf install mesa-libGL (RHEL).
version solving failed ... depends on numpy (>=2.0.2,<3.0.0) and docling requires numpy (>=1.26.4,<2.0.0)
Warum das passiert: Unter Python 3.13 benötigt Docling numpy 2.x, ältere LangChain- oder andere Pins erzwingen jedoch numpy 1.x; ein Resolver kann beides nicht erfüllen.
Schnelle Lösung: Schließen Sie Python 3.13 aus dem Python-Bereich Ihres Projekts aus.
Empfohlene Lösung: Setzen Sie python = ">=3.10,<3.13" in pyproject.toml oder aktualisieren Sie docling-ibm-models>=2.0.7 und deepsearch-glm>=0.26.2. Für gemischte Anforderungen nutzen Sie numpy-Marker je Python-Version.
python = ">=3.10,<3.13"
Wenn das nicht zutrifft: Einige Drittanbieter-Pakete haben noch keine Python-3.13-Wheels.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate>
Warum das passiert: Die Liste der vertrauenswürdigen Zertifikate der Python-Umgebung ist veraltet, wenn Modellgewichte von Hugging Face geladen werden.
Schnelle Lösung: Aktualisieren Sie certifi.
Empfohlene Lösung: pip install --upgrade certifi. Besteht das Problem weiter, richten Sie SSL_CERT_FILE und REQUESTS_CA_BUNDLE auf `python -m certifi` oder installieren Sie pip-system-certs.
pip install --upgrade certifi
Wenn das nicht zutrifft: Hinter einem Unternehmensproxy konfigurieren Sie zusätzlich HTTPS_PROXY und Ihre interne Root-CA.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
docling: command not found / Docling version: unknown
Warum das passiert: Ein Upgrade einer älteren Installation kann das docling-Konsolenskript deregistrieren, da das Projekt in docling und docling-slim aufgeteilt wurde.
Schnelle Lösung: Installieren Sie das Paket, das den Befehl bereitstellt, neu.
Empfohlene Lösung: pip install --force-reinstall docling (oder pip install -U docling docling-slim), dann docling --version. Stellen Sie in einer virtuellen Umgebung sicher, dass bin/Scripts im PATH liegt.
pip install --force-reinstall docling
Wenn das nicht zutrifft: uv tool install docling kann aus demselben Grund fehlschlagen; nutzen Sie docling-slim[standard].
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
'pip' is not recognized as an internal or external command
Warum das passiert: Embedded Python oder eine Standard-Windows-Installation fügt Python und Scripts nicht zum PATH hinzu.
Schnelle Lösung: Nutzen Sie eine normale Python-Installation und eine virtuelle Umgebung statt Embedded Python.
Empfohlene Lösung: Installieren Sie Python 3.12 von python.org mit „Add python.exe to PATH“, erstellen Sie ein venv (py -m venv .venv), aktivieren Sie es und folgen Sie pip install docling. Fehlt pip: py -m ensurepip --upgrade.
py -m venv .venv && .venv\Scripts\activate
Wenn das nicht zutrifft: Embedded Python ist nicht für installierte Konsolenskripte gedacht und für Docling nicht empfohlen.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
OSError / ConnectionError while downloading ds4sd/docling-models / a partial cache blocks later runs
Warum das passiert: Der erste PDF-Lauf lädt Layout-, Tabellen- und OCR-Modelle; ein fehlgeschlagener oder teilweiser Download hinterlässt einen defekten Cache.
Schnelle Lösung: Führen Sie den Lauf mit funktionierender Verbindung erneut aus oder laden Sie die Modelle vorab.
Empfohlene Lösung: Laden Sie alle Modelle vorab mit docling-tools models download --all und richten Sie DOCLING_CACHE_DIR auf einen beschreibbaren Ort.
docling-tools models download --all
Wenn das nicht zutrifft: Air-Gapped-Rechner benötigen zuerst eine Kopie des Caches von einem verbundenen Host.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
Offline-Modelle werden ignoriert (kontaktiert weiter Hugging Face)
Modelle & Cache
Still tries to reach huggingface.co / FileNotFoundError: Missing .../model.safetensors
Warum das passiert: Der artifacts_path zeigt auf das falsche Verzeichnis oder die Ordnerstruktur entspricht nicht den Erwartungen von Docling.
Schnelle Lösung: Richten Sie Docling auf den übergeordneten Ordner, der die Modell-Unterordner enthält.
Empfohlene Lösung: Führen Sie docling-tools models download -o ./models aus und setzen Sie artifacts_path="./models" (absoluter Pfad in Containern). Der Ordner muss Unterordner wie ds4sd--docling-models mit model.safetensors, config.json und preprocessor_config.json direkt darin enthalten.
docling-tools models download -o ./models
Wenn das nicht zutrifft: Umgebungsvariablen allein reichen für die Python-API nicht aus; übergeben Sie artifacts_path explizit.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
403 Client Error / rate limit exceeded / HTTPError while downloading model weights
Warum das passiert: Gated-Repositories, Ratenlimits oder ein Unternehmensproxy blockieren anonyme Hugging-Face-Downloads.
Schnelle Lösung: Authentifizieren Sie sich mit einem Hugging-Face-Token.
Empfohlene Lösung: export HF_TOKEN=your_token (oder huggingface-cli login) und erhöhen Sie die Timeouts mit HF_HUB_ETAG_TIMEOUT und HF_HUB_DOWNLOAD_TIMEOUT. Hinter einem Proxy HTTPS_PROXY setzen.
export HF_TOKEN=your_token
Wenn das nicht zutrifft: Manche Modelle erfordern zuerst das Akzeptieren einer Lizenz auf Hugging Face.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
Warum das passiert: Hugging Face versucht, Cache-Einträge oder Symlinks in einem schreibgeschützten Mount anzulegen, während lokale Modelle geladen werden.
Schnelle Lösung: Richten Sie den Cache auf einen beschreibbaren Pfad.
Empfohlene Lösung: Setzen Sie HF_HOME und HF_HUB_CACHE auf ein beschreibbares Verzeichnis und HF_HUB_OFFLINE=1, sobald alle Modelle vorhanden sind; binden Sie das Modellverzeichnis als Daten ein, nicht als Hugging-Face-Cache.
export HF_HUB_CACHE=/tmp/hf-cache
Wenn das nicht zutrifft: HF_HUB_OFFLINE=1 deaktiviert jeglichen Netzwerkzugriff; stellen Sie sicher, dass alle Modelle vorliegen.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
ModuleNotFoundError: No module named 'tesserocr' / OCR engine import fails
Warum das passiert: Einige OCR-Engines benötigen Systembinärdateien (z. B. Tesseract), die pip nicht installieren kann.
Schnelle Lösung: Nutzen Sie RapidOCR oder EasyOCR, die reines Python sind und sich leichter installieren lassen.
Empfohlene Lösung: pip install "docling[rapidocr]" oder "docling[easyocr]". Für Tesseract zuerst die Systembinärdatei installieren (brew/apt/dnf), dann das Extra.
pip install "docling[rapidocr]"
Wenn das nicht zutrifft: Tesseract benötigt zusätzlich Sprachdaten; setzen Sie TESSDATA_PREFIX, wenn Sprachen fehlen.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
Error: Failed loading language 'deu' / TESSDATA_PREFIX is not set
Warum das passiert: Tesseract benötigt die .traineddata-Dateien und einen korrekten TESSDATA_PREFIX, der auf den tessdata-Ordner zeigt.
Schnelle Lösung: Installieren Sie die Sprachpakete und setzen Sie TESSDATA_PREFIX (muss mit einem Schrägstrich enden).
Empfohlene Lösung: apt-get install tesseract-ocr-eng tesseract-ocr-deu (Debian), dann export TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata/. Setzen Sie ocr_options.lang auf die installierten Sprachen.
Warum das passiert: Ohne DPI-Metadaten gerenderte Seitenbilder können Tesseract stören, besonders bei Bildern aus Containern.
Schnelle Lösung: Versuchen Sie eine andere OCR-Engine oder rendern Sie Seiten zuerst mit explizitem DPI in Bilder.
Empfohlene Lösung: Wechseln Sie zu RapidOCR oder EasyOCR, oder rendern Sie vorab mit fester Dichte (ImageMagick: convert -density 216 input.pdf page.png) und OCRn Sie das Bild.
convert -density 216 input.pdf page.png
Wenn das nicht zutrifft: Dies ist eine Tesseract-Eigenheit; andere Engines sind nicht betroffen.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
Non-English text comes out garbled or empty / wrong characters
Warum das passiert: Die OCR-Engine verwendet standardmäßig einen begrenzten Sprachumfang.
Schnelle Lösung: Setzen Sie die OCR-Sprachen in den Pipeline-Optionen.
Empfohlene Lösung: pipeline_options.ocr_options.lang = ["fr", "de", "en"] — die gewählte Engine muss diese Sprachen unterstützen, und für Tesseract müssen die Sprachdaten installiert sein.
torch.cuda.is_available() is False / processing stays on the CPU
Warum das passiert: PyTorch wurde ohne CUDA-Unterstützung installiert, oder es ist keine kompatible GPU und kein Treiber verfügbar.
Schnelle Lösung: Prüfen Sie, ob torch.cuda.is_available() True zurückgibt.
Empfohlene Lösung: Deinstallieren Sie die CPU-Wheels und installieren Sie CUDA-fähiges PyTorch passend zu Ihrer CUDA-Version, dann --device cuda wählen. Prüfen Sie mit nvidia-smi.
torch.cuda.OutOfMemoryError: CUDA out of memory. Tried to allocate ...
Warum das passiert: Die Batch-Größen übersteigen den verfügbaren VRAM, oder ein anderer Prozess belegt GPU-Speicher.
Schnelle Lösung: Reduzieren Sie die Batch-Größen und leeren Sie den Cache.
Empfohlene Lösung: Verringern Sie layout_batch_size, ocr_batch_size und table_batch_size, setzen Sie queue_max_size, rufen Sie torch.cuda.empty_cache() zwischen Dokumenten auf und verarbeiten Sie weniger Dateien parallel.
import torch
torch.cuda.empty_cache()
pipeline_options.ocr_batch_size = 2
Wenn das nicht zutrifft: Sehr große Seiten können weiterhin den VRAM sprengen; weichen Sie für diese Dateien auf die CPU aus.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
CUDA error: no kernel image is available for execution on the device
Warum das passiert: Der CUDA-Build von PyTorch enthält keine Kernel für die Compute-Capability Ihrer GPU, was bei sehr neuen GPUs oder altem Treiber häufig vorkommt.
Schnelle Lösung: Nutzen Sie einen PyTorch- oder Container-Build, der zu Ihrer GPU und Ihrem Treiber passt.
Empfohlene Lösung: Prüfen Sie Treiber-/CUDA-Kompatibilität, aktualisieren Sie den NVIDIA-Treiber und nutzen Sie das passende CUDA-Wheel (cu128/cu130) oder das passende docling-serve-CUDA-Image. In Docker die GPU über das NVIDIA Container Toolkit bereitstellen.
nvidia-smi
Wenn das nicht zutrifft: Brandneue GPUs benötigen möglicherweise einen neueren CUDA-Build als das aktuelle Image bietet.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
Flash Attention 2 lässt sich nicht installieren oder importieren
GPU
flash-attn fails to build / ImportError: cannot import name 'flash_attn'
Warum das passiert: Flash Attention 2 erfordert eine Ampere- oder neuere GPU, CUDA 11.8+ und PyTorch 2.0+ und ist schwer aus dem Quellcode zu bauen.
Schnelle Lösung: Deaktivieren Sie es, wenn Sie es nicht benötigen.
Empfohlene Lösung: Setzen Sie accelerator_options = AcceleratorOptions(cuda_use_flash_attention2=False) oder installieren Sie mit FLASH_ATTENTION_SKIP_CUDA_BUILD=TRUE pip install flash-attn.
torch.backends.mps.is_available() is False / inference falls back to CPU
Warum das passiert: MPS erfordert macOS 12.3+ auf einem M-Chip und einen PyTorch-Build mit MPS; einige Operationen fallen weiterhin auf die CPU zurück.
Schnelle Lösung: Nutzen Sie device auto, damit Docling das beste verfügbare Gerät wählt.
Empfohlene Lösung: Führen Sie auf Apple Silicon mit --device mps aus und aktualisieren Sie macOS und PyTorch; nutzen Sie auto für den automatischen Rückfall.
docling convert report.pdf --device mps
Wenn das nicht zutrifft: Einige Modelle führen Teile der Pipeline weiterhin auf der CPU aus.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
Warum das passiert: OCR- und Enrichment-Modelle sind teuer, besonders auf der CPU.
Schnelle Lösung: Deaktivieren Sie OCR bei digitalen PDFs und schalten Sie nicht benötigtes Enrichment ab.
Empfohlene Lösung: Nutzen Sie --no-ocr für Text-PDFs, --table-mode fast, wenn Genauigkeit erlaubt ist, generate_page_images=False und möglichst eine GPU. Passen Sie --num-threads an Ihre CPU-Kerne an.
docling convert report.pdf --no-ocr --to md
Wenn das nicht zutrifft: Gescannte Dokumente benötigen OCR und können es nicht überspringen.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
Killed / std::bad_alloc / the process is OOM-killed
Warum das passiert: Große, bild- oder formelreiche PDFs können den RAM erschöpfen, und das docling-parse-Backend kann Speicher über Seiten hinweg ansammeln.
Schnelle Lösung: Verarbeiten Sie die PDF in Seitenbereichen oder teilen Sie sie in kleinere Dateien.
Empfohlene Lösung: converter.convert("large.pdf", page_range=[1, 100]); für sehr große Dateien auf die PyPdfium-Backends wechseln; Enrichment deaktivieren; generate_parsed_pages=False beibehalten; in einem Subprozess zwischen Dateien neu starten.
docling convert large.pdf --page-range 1-100
Wenn das nicht zutrifft: Das Aufteilen kann Überschriften und mehrseitige Tabellen an den Grenzen zerstören.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
RAM rises steadily when processing a batch / DoclingLoader leaks memory
Warum das passiert: Das PDF-Backend behält Caches und Dokumentreferenzen nach jeder Konvertierung.
Schnelle Lösung: Geben Sie das Backend nach jeder Datei explizit frei.
Empfohlene Lösung: Rufen Sie nach der Konvertierung result.input._backend.unload() auf, erstellen Sie den DocumentConverter alle paar Dateien neu oder nutzen Sie einen Subprozess pro Datei. Halten Sie docling, docling-core und docling-parse aktuell.
result.input._backend.unload()
Wenn das nicht zutrifft: Formula-Enrichment hat ein eigenes bekanntes Leck; isolieren Sie es in einem separaten Prozess.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
ConversionError: Input document file.pdf is not valid / status FAILURE
Warum das passiert: Die Datei kann verschlüsselt, beschädigt, passwortgeschützt oder eine nicht unterstützte Variante sein.
Schnelle Lösung: Testen Sie eine andere Beispieldatei, um zu klären, ob das Dokument oder das Setup das Problem ist.
Empfohlene Lösung: Entfernen Sie den Passwortschutz oder übergeben Sie --pdf-password; reparieren oder exportieren Sie die Datei neu; prüfen Sie die Liste der unterstützten Formate und eröffnen Sie ein Issue mit Beispiel.
docling convert report.pdf --to md
Wenn das nicht zutrifft: Verschlüsselte PDFs werden nicht still entschlüsselt; liefern Sie eine ungeschützte Kopie oder das Passwort.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
Warum das passiert: PDFs mit benutzerdefinierten eingebetteten Fonts ohne ToUnicode-Zuordnung lassen sich nicht in echte Zeichen abbilden.
Schnelle Lösung: Erzwingen Sie vollseitiges OCR.
Empfohlene Lösung: Setzen Sie pipeline_options.ocr_options.force_full_page_ocr = True (oder --ocr-mode full_page). Alternativ auf das PyPdfium2-Backend wechseln, das diese Fonts manchmal besser dekodiert.
docling convert broken.pdf --ocr-mode full_page
Wenn das nicht zutrifft: OCR kann in manchen Versionen GLYPHs in Tabellen übersehen; aktualisieren Sie Docling.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
"fi" / "fl" / "ffi" appear with spaces, e.g. "e ffi cient"
Warum das passiert: Einige PDF-Fonts ordnen Ligatur-Glyphen separaten Zeichen mit überflüssigen Leerzeichen zu.
Schnelle Lösung: Aktualisieren Sie Docling, das gängige Ligaturen normalisiert.
Empfohlene Lösung: Modernes Docling bereinigt Ligaturen in der Page-Assemble-Stufe. Bricht Ihre PDF weiterhin, nutzen Sie OCR oder bereiten Sie den Font vor.
pip install -U docling
Wenn das nicht zutrifft: Glyph-namenbasierte Ligaturen können weiterhin durchrutschen, wenn das Backend sie nicht dekodiert.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
Images are missing from DOCX or PPTX output on macOS or Linux
Warum das passiert: Die WMF/EMF-Bildverarbeitung funktioniert nur unter Windows mit der Standard-Bildbibliothek.
Schnelle Lösung: Konvertieren Sie die Bilder oder führen Sie die Konvertierung unter Windows aus.
Empfohlene Lösung: Wandeln Sie WMF/EMF-Assets vor der Konvertierung in PNG/SVG um (z. B. mit LibreOffice headless) oder führen Sie diesen Schritt unter Windows aus.
Konvertierung einer URL schlägt fehl (403 oder Timeout)
Konvertierung
HTTPError 403/404 or a timeout when converting an URL
Warum das passiert: Der Server blockiert anonyme Anfragen, die URL ist eine Landingpage, oder die Verbindung läuft in einen Timeout.
Schnelle Lösung: Laden Sie die Datei zuerst herunter und übergeben Sie den lokalen Pfad.
Empfohlene Lösung: Übergeben Sie in Python eigene Header: converter.convert(url, headers={"User-Agent": "..."}). Vergewissern Sie sich, dass die URL auf eine PDF/DOCX und nicht auf eine HTML-Seite zeigt.
docling convert ./downloaded.pdf --to md
Wenn das nicht zutrifft: Manche Seiten erfordern Cookies oder Authentifizierung, die Docling nicht verarbeitet.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
Wrong table structure / cells merged or columns shifted
Warum das passiert: Komplexe verbundene Zellen und rahmenlose Tabellen sind schwierig, und der Fast-Modus tauscht Genauigkeit gegen Geschwindigkeit.
Schnelle Lösung: Nutzen Sie den genauen Tabellenmodus.
Empfohlene Lösung: Führen Sie mit --table-mode accurate aus. Bei TableFormer-V2-Problemen mit verbundenen Zellen versuchen Sie do_cell_matching=False oder fallen auf V1 zurück und halten Docling aktuell.
docling convert report.pdf --table-mode accurate
Wenn das nicht zutrifft: Kein Parser ist bei jeder Tabelle perfekt; manuelle Prüfung kann nötig sein.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
A whitespace-aligned table is extracted as prose / the table is missed
Warum das passiert: Das Layoutmodell kann Tabellen ohne sichtbare Rahmen übersehen und ausgerichtete Spalten als normalen Text behandeln.
Schnelle Lösung: Versuchen Sie erzwungenes OCR oder ein anderes Backend.
Empfohlene Lösung: Erzwingen Sie OCR, was das Raster sichtbar machen kann, wechseln Sie zum PyPdfium2-Backend oder erhöhen Sie images_scale. Prüfen Sie kritische Dokumente manuell.
docling convert report.pdf --ocr-mode full_page
Wenn das nicht zutrifft: Wenn das Layoutmodell die Region nie markiert, kann nachgelagerter Code sie nicht wiederherstellen.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
Warum das passiert: Das Layoutmodell benötigt etwas Rand zwischen Tabelle und Seitenbegrenzung, um sie zu unterscheiden.
Schnelle Lösung: Fügen Sie vor der Konvertierung einen kleinen weißen Rand um die Seite hinzu.
Empfohlene Lösung: Fügen Sie der PDF vor der Konvertierung etwa 40pt links/rechts Padding hinzu (z. B. mit pypdf); eine native page_padding-Option wird upstream diskutiert.
python add_padding.py input.pdf
Wenn das nicht zutrifft: Externes Padding kann das Layout mancher Dokumente verändern.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
docling-serve does not start / connection refused on port 5001
Warum das passiert: Ein Portkonflikt, ein fehlendes UI-Extra oder ein Container, der einen anderen Entrypoint benötigt.
Schnelle Lösung: Führen Sie den Server mit dem UI-Extra aus und prüfen Sie, ob der Port frei ist.
Empfohlene Lösung: pip install "docling-serve[ui]" && docling-serve run --enable-ui oder das offizielle Container-Image nutzen. Bind-Adresse oder Port mit UVICORN_HOST/UVICORN_PORT ändern.
docling-serve run --enable-ui
Wenn das nicht zutrifft: Fortgeschrittenes Deployment (Skalierung, Auth) liegt außerhalb des Umfangs; siehe offizielle Docs.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
docling-serve liefert 503 oder startet mit Timeout
Server, API & MCP
GET /ready returns 503 / requests time out while models load
Warum das passiert: Der /ready-Endpunkt bleibt 503, bis die Modelle geladen sind, und beim RQ-Engine bis Redis erreichbar ist.
Schnelle Lösung: Warten Sie auf die Bereitschaft, bevor Sie Traffic senden.
Empfohlene Lösung: Konfigurieren Sie startupProbe und readinessProbe auf /ready und eine livenessProbe auf /health und laden Sie Modelle mit DOCLING_SERVE_ARTIFACTS_PATH vor, um den Start zu verkürzen.
curl -i http://localhost:5001/ready
Wenn das nicht zutrifft: Mit der RQ-Engine erfordert /ready zusätzlich Redis-Konnektivität.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
CUDA error: no kernel image is available / the container runs on CPU despite --gpus
Warum das passiert: Der Container hat keinen GPU-Zugriff, oder CUDA-Image-Tag und Host-Treiber passen nicht zusammen.
Schnelle Lösung: Stellen Sie die GPU über das NVIDIA Container Toolkit bereit.
Empfohlene Lösung: Installieren und aktualisieren Sie nvidia-container-toolkit, konfigurieren Sie die nvidia-Runtime und fordern Sie die GPU an (docker run --gpus all oder devices count: all in Compose). Nutzen Sie den CUDA-Image-Tag passend zu Ihrem Treiber.
docker run --gpus all -p 5001:5001 quay.io/docling-project/docling-serve-cu128
Wenn das nicht zutrifft: Einige sehr neue GPUs erfordern ein neueres CUDA-Image als derzeit veröffentlicht.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
The MCP server is not listed in the client / no tools appear / the server exits immediately
Warum das passiert: Die Client-Konfiguration zeigt auf den falschen Befehl, das Paket ist nicht verfügbar oder der Transport ist falsch.
Schnelle Lösung: Starten Sie den Server einmal manuell, um zu prüfen, ob er funktioniert.
Empfohlene Lösung: uvx --from=docling-mcp docling-mcp-server und das passende JSON in claude_desktop_config.json (oder mcp.json) eintragen. Client neu starten und bei Bedarf --transport stdio ergänzen.
uvx --from=docling-mcp docling-mcp-server
Wenn das nicht zutrifft: Die Konfigurationsdateien unterscheiden sich je Client; prüfen Sie die Client-Dokumentation.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
MCP kann nicht auf Dateien zugreifen oder läuft in einen Timeout
Server, API & MCP
[Errno 2] No such file or directory / the MCP client times out on a cold start
Warum das passiert: Der MCP-Server sieht das Dateisystem des Clients nicht, oder die erste Konvertierung ist langsam, während Modelle laden.
Schnelle Lösung: Nutzen Sie ein gemeinsames Verzeichnis oder wechseln Sie über docling-serve in den Remote-Modus.
Empfohlene Lösung: Setzen Sie DOCLING_MCP_CONVERSION_MODE=remote mit DOCLING_MCP_SERVICE_URL oder binden Sie einen gemeinsamen Ordner ein, den beide Prozesse lesen. Wärmen Sie den Modell-Cache vor, um Cold-Start-Timeouts zu vermeiden.
export DOCLING_MCP_CONVERSION_MODE=remote
Wenn das nicht zutrifft: Web-Clients teilen kein Dateisystem mit einem lokalen MCP-Server.
Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22
Die meisten Docling-Probleme entstehen durch eine veraltete Version, ein fehlendes optionales Extra oder ein einzelnes schwieriges Dokument. Arbeiten Sie diese Schritte zuerst durch.
Fehlertext zuordnen. Durchsuchen Sie die Karten oben; die genaue Meldung steht meist als Symptom.
Zuerst aktualisieren. Viele Probleme sind bereits behoben: pip install -U docling docling-core docling-parse.
Mit einer einfachen Datei reproduzieren. Funktioniert eine kleine, einfache PDF oder DOCX, liegt das Problem meist am Dokument, nicht an der Installation.
Eine Sache ändern. Probieren Sie --pdf-backend pypdfium2, --ocr-mode full_page oder --table-mode fast.
Umfang reduzieren. Nutzen Sie --page-range, deaktivieren Sie Enrichment und konvertieren Sie eine einzelne Datei.
Details sammeln bevor Sie melden (nächste Karte).
2
Schritt 2
Umgebung erfassen
Kopieren Sie diese Befehle, damit Versionsnummern und Geräteinformationen bereitliegen, wenn etwas fehlschlägt.
Geben Sie den genauen Befehl und den vollständigen Traceback an.
Hängen Sie nach Möglichkeit ein minimales Beispieldokument an.
Nennen Sie Betriebssystem, Python-Version und ob Sie Docker nutzen.
Fügen Sie -vv für ausführliche Konvertierungslogs hinzu.
Die PDF-Konvertierung benötigt Modellgewichte; ein defekter oder blockierter Download ist ein sehr häufiger Fehler.
Laden Sie alles vorab mit docling-tools models download --all.
Richten Sie artifacts_path auf den übergeordneten Ordner der Modell-Unterordner.
Setzen Sie HF_HOME für einen Cache-Ort und HF_TOKEN hinter einem Proxy oder für gated Repos.
Für Air-Gapped-Hosts zuerst den Cache von einem verbundenen Rechner kopieren.
5
Schritt 5
OCR
OCR-Probleme sind meist eine fehlende Engine, fehlende Sprachdaten oder der falsche Modus.
Installieren Sie eine Engine: pip install "docling[rapidocr]" oder [easyocr].
Für Tesseract die Systembinärdatei und Sprachpakete installieren und TESSDATA_PREFIX setzen.
Erzwingen Sie OCR für Scans und Glyph-PDFs mit --ocr-mode full_page.
Vergleichen Sie Engines auf der Seite OCR-Engines.
6
Schritt 6
GPU, Speicher & Geschwindigkeit
Langsame oder abgebrochene Konvertierungen sind meist Speicherdruck oder reine CPU-Ausführung.
Prüfen Sie CUDA/MPS, reduzieren Sie Batch-Größen und rufen Sie torch.cuda.empty_cache() auf.
Verarbeiten Sie riesige PDFs mit --page-range oder wechseln Sie zum PyPdfium-Backend.
Geben Sie Speicher mit result.input._backend.unload() zwischen Dateien frei.
Deaktivieren Sie nicht benötigtes OCR und Enrichment; passen Sie --num-threads an.
7
Schritt 7
Konvertierung, Tabellen & Formate
Ausgabeprobleme lassen sich meist auf das Quelldokument, das Backend oder den Tabellenmodus zurückführen.
Passwort-PDFs: --pdf-password übergeben.
GLYPH oder unlesbarer Text: vollseitiges OCR erzwingen oder Backend wechseln.
Tabellen: --table-mode accurate verwenden; bei V2-verbundenen-Zellen do_cell_matching=False oder V1 versuchen.
Stapeljobs: raises_on_error=False setzen und jedes Ergebnis prüfen.
8
Schritt 8
Server, API & MCP
Der Dienst und die Agent-Integrationen scheitern aus drei Gründen: Ports, Bereitschaft oder GPU-Zugriff.
Starten Sie die API mit docling-serve run --enable-ui (oder dem Container-Image).
/ready bleibt 503, bis Modelle geladen sind; als Startup-/Readiness-Probe nutzen.
In Docker die GPU bereitstellen (--gpus all) und das NVIDIA Container Toolkit installieren.
Für MCP uvx --from=docling-mcp docling-mcp-server ausführen; für Web-Clients den Remote-Modus nutzen.
9
Schritt 9
RAG, Audio & Video
Chunking-Warnungen sind meist harmlos; Audio und Video benötigen zusätzliche Abhängigkeiten.
Die HybridChunker-Token-Warnung ist ein Fehlalarm; prüfen Sie stattdessen die echten Chunk-Größen.
Installieren Sie docling-core[chunking] für den tokenisierungsbewussten Chunker.
Audio und Video benötigen pip install "docling[asr]" und ffmpeg im PATH.
Siehe die RAG-Anleitung für die vollständige Pipeline.
10
Schritt 10
Einen Fehler melden
Eine gute Meldung führt zu einer schnellen Korrektur. Fügen Sie alles zur Reproduktion Nötige bei.
Suchen Sie zuerst nach vorhandenen Issues, um Duplikate zu vermeiden.
Nennen Sie die Versionen von Docling, docling-core und Python.
Fügen Sie den genauen Befehl und den vollständigen Traceback ein.
Hängen Sie ein minimales Beispieldokument an, wenn es nicht vertraulich ist.
Stellen Sie Nutzungsfragen in den Discussions, nicht im Issue-Tracker.
11
Schritt 11
Häufig gestellte Fragen
Welchen Fehler sollte ich zuerst beheben?
Beginnen Sie mit Installations- und Modellfehlern. Nichts anderes funktioniert, bis Docling installiert ist und seine Modelle laden kann.
Ich habe aktualisiert und etwas ist kaputt. Was tun?
Fixieren Sie die vorige Version mit pip install docling==<version>, um sich zu entblocken, und melden Sie die Regression mit Beispiel.
Wird mein Dokument irgendwohin gesendet?
Nein. Docling läuft lokal und sendet keine Dokumentdaten. Der einzige Netzwerkzugriff ist der Download von Modellgewichten.
Muss ich große PDFs aufteilen?
Nur bei Speichergrenzen. Versuchen Sie zuerst --page-range, dann das Aufteilen, und rechnen Sie mit etwas Verlust seitenübergreifender Struktur.
Warum werden meine Tabellen falsch extrahiert?
Komplexe verbundene Zellen und rahmenlose Tabellen sind schwierig. Nutzen Sie den genauen Modus, versuchen Sie do_cell_matching=False oder TableFormer V1 und prüfen Sie kritische Tabellen.
Die CLI funktioniert, Python nicht. Warum?
Nutzen Sie für beides dieselbe virtuelle Umgebung und übergeben Sie Optionen über PdfFormatOption, damit sie die Pipeline erreichen.
Wo bekomme ich weitere Hilfe?
Durchsuchen Sie die offiziellen GitHub-Issues und -Discussions und nennen Sie Ihre Versionen, den Befehl und den Traceback.