Paste your error#
Paste the error message or the last lines of the traceback. Matching runs in your browser; nothing is sent anywhere. Browse by category to read every entry.
Debugging any Docling failure in four steps#
- Confirm the version and Python
docling --version python --versionMost “unknown option” and “missing feature” reports are an old Docling, often caused by Python 3.9.
- Get the real error
docling convert problem.pdf -vv 2>&1 | tail -40 - Isolate the stage
Re-run with
--no-ocr, then--no-tables. If the error disappears, the problem is in that stage (often an OCR engine or its language). - Look at what Docling saw
docling convert problem.pdf --to html_split_page --show-layoutEach page is shown next to the extracted content with layout boxes drawn — the fastest way to diagnose bad tables, missing text or wrong reading order.
When the output is wrong but nothing fails#
| Symptom | Likely cause | Try |
|---|---|---|
| Scanned PDF comes out empty or garbled | The PDF has a bad text layer, so OCR is skipped | --ocr-mode full_page |
| Text looks right in the viewer but extracts as gibberish (“8VceZWZTReV”) | A font maps its glyphs to the wrong characters | --replace-broken-text-layer (2.144.0+) OCRs only the affected pages — see the OCR guide |
All headings come out as ## | The layout model labels section headers but not their level | --heading-hierarchy (2.144.0+) |
| Scanned page turned sideways reads as garbage with RapidOCR | RapidOCR's line classifier only flips text by 180° | --ocr-option detect_orientation=true (2.145.0+) |
| Wrong characters in a non-English scan | The OCR model's default language | --ocr-lang with the engine's code or iso: tag — see the OCR guide |
| Two table rows merged into one cell | Table without horizontal rules (we reproduced this on the Docling report's own Table 1) | Check with --show-layout; try the VLM pipeline on that page |
| Words run together (“MaksymLysak”) | Tight letter spacing in the PDF's text layer | Compare --pdf-backend pypdfium2; or --ocr-mode full_page |
| Huge Markdown files | Embedded base64 images (CLI default embedded) | --image-export-mode placeholder or referenced |
| Headers and footers in the text | Reading the full document including furniture | Export the body only (the default Markdown export skips page headers/footers) |
| Chunks cut mid-table or too long for embeddings | HierarchicalChunker or a mismatched tokenizer | HybridChunker with your embedding model's tokenizer — see RAG & chunking |
Still stuck?#
Search the official issue tracker with the exact error text, and include docling --version output, your OS and a minimal file if you open a new issue. If an entry on this page is wrong or a fix stopped working, email hello@docling.org.
Frequently asked questions
Why does Docling say onnxruntime is not installed?
Because --ocr-engine rapidocr uses RapidOCR's onnxruntime backend, which the default pip install docling does not include. Install docling[rapidocr], or add --ocr-option backend=torch to use the PyTorch backend that is already installed.
Why are new Docling options missing after installing?
Check docling --version. On Python 3.9, pip installs Docling 2.69.1, the last version that supports 3.9, without an error. Use Python 3.10–3.14 to get current releases.
How do I see why a document failed in Docling?
Run the same file with -vv for debug logs. The CLI's 'Document … failed to convert' line is only a summary; the actual exception is logged above it.
Why does Docling fail on .doc, .ppt or .xls files?
Those legacy formats (and .rtf) are converted to .docx, .pptx or .xlsx with LibreOffice first. Install LibreOffice so that soffice is on PATH, or set DOCLING_LIBREOFFICE_CMD.
Sources
- Docling 2.148.0 source code (error messages)
- Docling GitHub issues
- Granite-Docling model card: troubleshooting
- docling-serve 1.38.2 source