A curated set of the problems Docling users actually hit, with the exact error text, a quick fix, a recommended fix and an official source. Filter by category or search for an error message.
bash — first response
$pip install -U docling
$docling --help
✓Search the exact error text in the cards below — symptoms are quoted verbatim.
✓Fix install + model errors first. Nothing else works until Docling installs and loads its models.
✓Still stuck? Report with versions, command and traceback.
Installation fails on Windows
Installation
error: Microsoft Visual C++ 14.0 or greater is required / Failed building wheel for docling-parse
Why it happens: Some optional dependencies compile native C++ or Rust extensions and need a compiler that is not present by default.
Quick fix: Install with Astral uv instead of pip to use pre-built wheels: uv add docling.
Recommended fix: If you must use pip, install the Microsoft Visual C++ Build Tools (14.0+) and a 64-bit Python, then retry. On an unsupported OS or Python, use a supported combination (Python 3.10-3.12) or a container.
uv add docling
When this does not apply: If no wheel exists for your OS and Python, the compiler route may still be required.
Verified with Docling v2.129.0 · Last checked 2026-09-22
Microsoft Visual C++ 14.0 is required. Get it with Microsoft C++ Build Tools
Why it happens: pip is building a native extension from source and cannot find the MSVC toolchain.
Quick fix: Prefer uv, which resolves pre-compiled wheels and avoids the compiler entirely.
Recommended fix: Otherwise install the Build Tools and select the Desktop development with C++ workload: winget install Microsoft.VisualStudio.2022.BuildTools.
Failed building wheel for docling-parse / ERROR: Failed to build installable wheels for some pyproject.toml based projects
Why it happens: No pre-built wheel is available for your platform or Python (for example macOS older than 13, Alpine/Termux, exotic architectures, or a very new Python), so pip tries to compile from source.
Quick fix: Use a supported platform and Python 3.10-3.12, and install with uv to fetch wheels.
Recommended fix: On macOS use macOS 13+ (Apple Silicon); on Linux prefer a mainstream x86_64/arm64 distro or the official container. Pin a docling version whose wheels match your platform, or build with a full C++ toolchain.
uv venv --python 3.12 && uv add docling
When this does not apply: 32-bit, musl/Alpine without build dependencies and some ARM systems are not officially supported.
Verified with Docling v2.129.0 · Last checked 2026-09-22
ImportError: libGL.so.1: cannot open shared object file: No such file or directory / ModuleNotFoundError: No module named 'cv2'
Why it happens: opencv-python (with the OpenGL UI) is installed in a headless environment such as Docker or a remote VM, or OpenCV is missing entirely in a fresh environment.
Quick fix: Force the headless OpenCV build.
Recommended fix: pip uninstall -y opencv-python opencv-python-headless && pip install --no-cache-dir opencv-python-headless. Alternatively install the system library: apt-get install libgl1 (Debian) or 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)
Why it happens: On Python 3.13 Docling needs numpy 2.x, but older LangChain or other pins force numpy 1.x; a resolver cannot satisfy both.
Quick fix: Exclude Python 3.13 from your project's Python range.
Recommended fix: Set python = ">=3.10,<3.13" in pyproject.toml, or upgrade docling-ibm-models>=2.0.7 and deepsearch-glm>=0.26.2. For mixed needs, use numpy markers per Python version.
python = ">=3.10,<3.13"
When this does not apply: Some third-party packages still have no Python 3.13 wheels.
Verified with Docling v2.129.0 · Last checked 2026-09-22
URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate>
Why it happens: The Python environment's list of trusted certificates is outdated when fetching model weights from Hugging Face.
Quick fix: Update certifi.
Recommended fix: pip install --upgrade certifi. If it persists, point SSL_CERT_FILE and REQUESTS_CA_BUNDLE at `python -m certifi`, or install pip-system-certs.
pip install --upgrade certifi
When this does not apply: Behind a corporate proxy, also configure HTTPS_PROXY and your internal root CA.
Verified with Docling v2.129.0 · Last checked 2026-09-22
docling: command not found / Docling version: unknown
Why it happens: Upgrading an older install can leave the `docling` console script unregistered because the project split into docling and docling-slim.
Quick fix: Reinstall the package that owns the command.
Recommended fix: pip install --force-reinstall docling (or pip install -U docling docling-slim), then run docling --version. In a virtual environment, make sure its bin/Scripts folder is on PATH.
pip install --force-reinstall docling
When this does not apply: uv tool install docling can fail for the same reason; install docling-slim[standard] instead.
Verified with Docling v2.129.0 · Last checked 2026-09-22
'pip' is not recognized as an internal or external command
Why it happens: Embedded Python or a default Windows install does not add Python and Scripts to PATH.
Quick fix: Use a normal Python install and a virtual environment instead of embedded Python.
Recommended fix: Install Python 3.12 from python.org with 'Add python.exe to PATH' checked, create a venv (py -m venv .venv), activate it, then pip install docling. If pip is missing: py -m ensurepip --upgrade.
py -m venv .venv && .venv\Scripts\activate
When this does not apply: Embedded Python is not designed for installed console scripts and is not recommended for Docling.
Verified with Docling v2.129.0 · Last checked 2026-09-22
Offline models are ignored (still contacts Hugging Face)
Models & cache
Still tries to reach huggingface.co / FileNotFoundError: Missing .../model.safetensors
Why it happens: The artifacts path points at the wrong directory, or the folder structure does not match what Docling expects.
Quick fix: Point Docling at the parent folder that contains the model subfolders.
Recommended fix: Run docling-tools models download -o ./models, then set artifacts_path="./models" (absolute path in containers). The folder must contain subfolders like ds4sd--docling-models with model.safetensors, config.json and preprocessor_config.json directly inside.
docling-tools models download -o ./models
When this does not apply: Environment variables alone are not enough for the Python API; pass artifacts_path explicitly.
Verified with Docling v2.129.0 · Last checked 2026-09-22
Models appear in both ./models and ~/.cache/huggingface
Why it happens: Hugging Face libraries keep their own global cache in addition to the directory you pass to Docling.
Quick fix: Set HF_HOME so downloads land in one directory.
Recommended fix: export HF_HOME=/your/cache (or HF_HUB_CACHE) before running, and pass the same folder as artifacts_path so Docling and Hugging Face agree.
export HF_HOME=./models-cache
When this does not apply: Docling passes your path through, but the underlying Hugging Face libraries still create their own cache.
Verified with Docling v2.129.0 · Last checked 2026-09-22
403 Client Error / rate limit exceeded / HTTPError while downloading model weights
Why it happens: Gated repositories, rate limits or a corporate proxy block anonymous Hugging Face downloads.
Quick fix: Authenticate with a Hugging Face token.
Recommended fix: export HF_TOKEN=your_token (or run huggingface-cli login) and raise the timeouts with HF_HUB_ETAG_TIMEOUT and HF_HUB_DOWNLOAD_TIMEOUT. Behind a proxy, set HTTPS_PROXY.
export HF_TOKEN=your_token
When this does not apply: Some models require accepting a license on Hugging Face before the download succeeds.
Verified with Docling v2.129.0 · Last checked 2026-09-22
Why it happens: Hugging Face tries to create cache entries or symlinks in a mount that is read-only while loading local models.
Quick fix: Point the cache at a writable path.
Recommended fix: Set HF_HOME and HF_HUB_CACHE to a writable directory and HF_HUB_OFFLINE=1 once all models are present; mount the model directory as data, not as the Hugging Face cache.
export HF_HUB_CACHE=/tmp/hf-cache
When this does not apply: HF_HUB_OFFLINE=1 disables all network access, so ensure every required model is present first.
Verified with Docling v2.129.0 · Last checked 2026-09-22
ModuleNotFoundError: No module named 'tesserocr' / OCR engine import fails
Why it happens: Some OCR engines need system-level binaries (for example Tesseract) that pip cannot install.
Quick fix: Use RapidOCR or EasyOCR, which are Python-only and easier to install.
Recommended fix: pip install "docling[rapidocr]" or "docling[easyocr]". For Tesseract, install the system binary first (brew/apt/dnf), then install the extra.
pip install "docling[rapidocr]"
When this does not apply: Tesseract also needs language data; set TESSDATA_PREFIX if languages are missing.
Verified with Docling v2.129.0 · Last checked 2026-09-22
Error: Failed loading language 'deu' / TESSDATA_PREFIX is not set
Why it happens: Tesseract needs the language .traineddata files and a correct TESSDATA_PREFIX pointing at the tessdata folder.
Quick fix: Install the language packs and set TESSDATA_PREFIX (it must end with a slash).
Recommended fix: apt-get install tesseract-ocr-eng tesseract-ocr-deu (Debian), then export TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata/. Set ocr_options.lang to the languages you installed.
Why it happens: Page images rendered without DPI metadata can trip Tesseract, especially for images generated inside containers.
Quick fix: Try a different OCR engine, or render pages to images with an explicit DPI first.
Recommended fix: Switch to RapidOCR or EasyOCR, or pre-render with a fixed density (ImageMagick: convert -density 216 input.pdf page.png) and OCR the image.
convert -density 216 input.pdf page.png
When this does not apply: This is a Tesseract-specific quirk; other engines are unaffected.
Verified with Docling v2.129.0 · Last checked 2026-09-22
Non-English text comes out garbled or empty / wrong characters
Why it happens: The OCR engine defaults to a limited language set.
Quick fix: Set the OCR languages in the pipeline options.
Recommended fix: pipeline_options.ocr_options.lang = ["fr", "de", "en"] — the selected engine must support those languages and, for Tesseract, the language data must be installed.
torch.cuda.is_available() is False / processing stays on the CPU
Why it happens: PyTorch was installed without CUDA support, or no compatible GPU and driver are available.
Quick fix: Check that torch.cuda.is_available() returns True in your environment.
Recommended fix: Uninstall the CPU wheels and install CUDA-enabled PyTorch for your CUDA version, then select the device with --device cuda. Verify with nvidia-smi.
torch.cuda.OutOfMemoryError: CUDA out of memory. Tried to allocate ...
Why it happens: Batch sizes exceed available VRAM, or another process is holding GPU memory.
Quick fix: Reduce the batch sizes and clear the cache.
Recommended fix: Lower layout_batch_size, ocr_batch_size and table_batch_size, set queue_max_size, call torch.cuda.empty_cache() between documents, and process fewer files in parallel.
import torch
torch.cuda.empty_cache()
pipeline_options.ocr_batch_size = 2
When this does not apply: Very large pages may still exceed VRAM; fall back to CPU for those files.
Verified with Docling v2.129.0 · Last checked 2026-09-22
CUDA error: no kernel image is available for execution on the device
Why it happens: The CUDA build of PyTorch does not include kernels for your GPU's compute capability, which is common on very new GPUs or with an old driver.
Quick fix: Use a PyTorch or container build that matches your GPU and driver.
Recommended fix: Check driver/CUDA compatibility, upgrade the NVIDIA driver, and use the matching CUDA wheel (cu128/cu130) or the matching docling-serve CUDA image. In Docker, expose the GPU with the NVIDIA container toolkit.
nvidia-smi
When this does not apply: Brand-new GPUs may need a newer CUDA build than your current image provides.
Verified with Docling v2.129.0 · Last checked 2026-09-22
flash-attn fails to build / ImportError: cannot import name 'flash_attn'
Why it happens: Flash Attention 2 requires an Ampere or newer GPU, CUDA 11.8+ and PyTorch 2.0+, and can be difficult to build from source.
Quick fix: Disable it if you do not need it.
Recommended fix: Set accelerator_options = AcceleratorOptions(cuda_use_flash_attention2=False), or install with FLASH_ATTENTION_SKIP_CUDA_BUILD=TRUE pip install flash-attn.
Why it happens: OCR and enrichment models are expensive, especially on CPU.
Quick fix: Disable OCR for digital PDFs and turn off enrichment you do not need.
Recommended fix: Use --no-ocr for text PDFs, --table-mode fast if accuracy allows, generate_page_images=False, and run on a GPU where possible. Tune --num-threads to your CPU cores.
docling convert report.pdf --no-ocr --to md
When this does not apply: Scanned documents genuinely require OCR and cannot skip it.
Verified with Docling v2.129.0 · Last checked 2026-09-22
Killed / std::bad_alloc / the process is OOM-killed
Why it happens: Large, image-heavy or math-heavy PDFs can exhaust RAM, and the docling-parse backend can accumulate memory across pages.
Quick fix: Process the PDF in page ranges or split it into smaller files.
Recommended fix: converter.convert("large.pdf", page_range=[1, 100]); switch to the PyPdfium backends for very large files; disable enrichment; keep generate_parsed_pages=False; run in a subprocess and restart between files.
docling convert large.pdf --page-range 1-100
When this does not apply: Splitting can break headings and multi-page tables that span the boundary.
Verified with Docling v2.129.0 · Last checked 2026-09-22
RAM rises steadily when processing a batch / DoclingLoader leaks memory
Why it happens: The PDF backend retains caches and document references after each conversion.
Quick fix: Release the backend explicitly after each file.
Recommended fix: Call result.input._backend.unload() after conversion, recreate the DocumentConverter every few files, or run one subprocess per file. Keep docling, docling-core and docling-parse current.
result.input._backend.unload()
When this does not apply: Formula enrichment has its own known leak; isolate it in a separate process.
Verified with Docling v2.129.0 · Last checked 2026-09-22
ConversionError: Input document file.pdf is not valid / status FAILURE
Why it happens: The file may be encrypted, corrupted, password-protected or an unsupported variant.
Quick fix: Try a different sample file to confirm whether the issue is the document or the setup.
Recommended fix: Remove password protection or pass --pdf-password; repair or re-export the file; check the supported-formats list and open an issue with a sample.
docling convert report.pdf --to md
When this does not apply: Encrypted PDFs are not silently decrypted; provide an unprotected copy or the password.
Verified with Docling v2.129.0 · Last checked 2026-09-22
Why it happens: PDFs with custom embedded fonts that lack a ToUnicode map cannot be mapped to real characters.
Quick fix: Force full-page OCR.
Recommended fix: Set pipeline_options.ocr_options.force_full_page_ocr = True (or --ocr-mode full_page). Alternatively switch to the PyPdfium2 backend, which sometimes decodes these fonts better.
docling convert broken.pdf --ocr-mode full_page
When this does not apply: OCR may still miss GLYPHs inside tables in some versions; upgrade Docling.
Verified with Docling v2.129.0 · Last checked 2026-09-22
HTTPError 403/404 or a timeout when converting an URL
Why it happens: The server blocks anonymous requests, the URL is a landing page, or the connection times out.
Quick fix: Download the file first and pass the local path.
Recommended fix: In Python pass custom headers: converter.convert(url, headers={"User-Agent": "..."}). Confirm the URL points to a PDF/DOCX and not an HTML page.
docling convert ./downloaded.pdf --to md
When this does not apply: Some sites require cookies or authentication that Docling does not handle.
Verified with Docling v2.129.0 · Last checked 2026-09-22
Wrong table structure / cells merged or columns shifted
Why it happens: Complex merged cells and borderless tables are hard, and fast mode trades accuracy for speed.
Quick fix: Use the accurate table mode.
Recommended fix: Run with --table-mode accurate. For TableFormer V2 merged-cell issues, try do_cell_matching=False or fall back to V1, and keep Docling updated.
docling convert report.pdf --table-mode accurate
When this does not apply: No parser is perfect on every table; some manual review may be needed.
Verified with Docling v2.129.0 · Last checked 2026-09-22
A whitespace-aligned table is extracted as prose / the table is missed
Why it happens: The layout model can miss tables with no visible borders, treating aligned columns as normal text.
Quick fix: Try forced OCR or a different backend.
Recommended fix: Force OCR, which can reveal the grid, switch to the PyPdfium2 backend, or increase images_scale. For critical documents, review manually.
docling convert report.pdf --ocr-mode full_page
When this does not apply: If the layout model never flags the region, downstream code cannot recover it.
Verified with Docling v2.129.0 · Last checked 2026-09-22
Why it happens: The layout model needs some margin between a table and the page boundary to distinguish them.
Quick fix: Add a small white margin around the page before conversion.
Recommended fix: Add roughly 40pt left/right padding to the PDF (for example with pypdf) before converting; a native page_padding option is under discussion upstream.
python add_padding.py input.pdf
When this does not apply: External padding can change the layout of some documents.
Verified with Docling v2.129.0 · Last checked 2026-09-22
docling-serve does not start / connection refused on port 5001
Why it happens: A port conflict, a missing UI extra, or a container that needs a different entrypoint.
Quick fix: Run the server with the UI extra and confirm the port is free.
Recommended fix: pip install "docling-serve[ui]" && docling-serve run --enable-ui, or use the official container image. Change the bind address or port with UVICORN_HOST/UVICORN_PORT.
docling-serve run --enable-ui
When this does not apply: Advanced deployment (scaling, auth) is out of scope; see the official docs.
Verified with Docling v2.129.0 · Last checked 2026-09-22
GET /ready returns 503 / requests time out while models load
Why it happens: The /ready endpoint stays 503 until models are loaded, and for the RQ engine until Redis is reachable.
Quick fix: Wait for readiness before sending traffic.
Recommended fix: Configure startupProbe and readinessProbe on /ready and a livenessProbe on /health, and pre-load models with DOCLING_SERVE_ARTIFACTS_PATH to shorten startup.
curl -i http://localhost:5001/ready
When this does not apply: With the RQ engine, /ready also requires Redis connectivity.
Verified with Docling v2.129.0 · Last checked 2026-09-22
CUDA error: no kernel image is available / the container runs on CPU despite --gpus
Why it happens: The container has no GPU access, or the CUDA image tag and the host driver do not match.
Quick fix: Expose the GPU with the NVIDIA container toolkit.
Recommended fix: Install and update nvidia-container-toolkit, configure the nvidia runtime, and request the GPU (docker run --gpus all, or devices count: all in Compose). Use the CUDA image tag that matches your driver.
docker run --gpus all -p 5001:5001 quay.io/docling-project/docling-serve-cu128
When this does not apply: Some very new GPUs require a newer CUDA image than is currently published.
Verified with Docling v2.129.0 · Last checked 2026-09-22
The MCP server is not listed in the client / no tools appear / the server exits immediately
Why it happens: The client config points at the wrong command, the package is not available, or the transport is wrong.
Quick fix: Launch the server once manually to confirm it works.
Recommended fix: uvx --from=docling-mcp docling-mcp-server and add the matching JSON to claude_desktop_config.json (or mcp.json). Restart the client and add --transport stdio if required.
uvx --from=docling-mcp docling-mcp-server
When this does not apply: Configuration file locations differ between clients; check the client's documentation.
Verified with Docling v2.129.0 · Last checked 2026-09-22
[Errno 2] No such file or directory / the MCP client times out on a cold start
Why it happens: The MCP server cannot see the client's filesystem, or the first conversion is slow while models load.
Quick fix: Use a shared directory, or switch to remote mode through docling-serve.
Recommended fix: Set DOCLING_MCP_CONVERSION_MODE=remote with DOCLING_MCP_SERVICE_URL, or mount a shared folder both processes can read. Pre-warm the model cache to avoid cold-start timeouts.
export DOCLING_MCP_CONVERSION_MODE=remote
When this does not apply: Web clients do not share a filesystem with a local MCP server.
Verified with Docling v2.129.0 · Last checked 2026-09-22
Verified with Docling v2.129.0 · Last checked 2026-09-22 · Official source
1
Triage
Start here: first response
Most Docling problems are caused by an out-of-date version, a missing optional extra, or a single difficult document. Work through these steps before anything else.
Match the error text. Search the cards above; the exact message is usually listed as a symptom.
Update first. Many issues are already fixed: pip install -U docling docling-core docling-parse.
Reproduce on a simple file. If a small, plain PDF or DOCX works, the problem is usually the document, not the install.
Change one thing. Try --pdf-backend pypdfium2, --ocr-mode full_page, or --table-mode fast.
Reduce the scope. Use --page-range, disable enrichment, and convert a single file.
Collect details before you report it (next card).
2
Diagnostics
Collect your environment
Copy these commands so you have the version numbers and device information ready when something fails.