Une liste sélectionnée de problèmes Docling courants avec correctif rapide, correctif recommandé et source officielle. Seuls des problèmes reproductibles sont listés.
L'installation échoue sous Windows
Installation
error: Microsoft Visual C++ 14.0 or greater is required / Failed building wheel for docling-parse
Pourquoi cela arrive : Certaines dépendances optionnelles compilent des extensions natives C++ ou Rust et nécessitent un compilateur absent par défaut.
Correctif rapide : Installez avec Astral uv plutôt que pip pour utiliser des wheels précompilés : uv add docling.
Correctif recommandé : Si vous devez utiliser pip, installez les Microsoft Visual C++ Build Tools (14.0+) et un Python 64 bits, puis réessayez. Sur un système ou un Python non pris en charge, utilisez une combinaison supportée (Python 3.10-3.12) ou un conteneur.
uv add docling
Quand cela ne s'applique pas : S'il n'existe aucun wheel pour votre système et votre Python, la voie du compilateur peut rester nécessaire.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Microsoft Visual C++ 14.0 is required. Get it with Microsoft C++ Build Tools
Pourquoi cela arrive : pip tente de compiler une extension native depuis les sources et ne trouve pas la chaîne d'outils MSVC.
Correctif rapide : Préférez uv, qui résout des wheels précompilés et évite totalement le compilateur.
Correctif recommandé : Sinon, installez les Build Tools avec la charge de travail Développement Desktop en C++ : winget install Microsoft.VisualStudio.2022.BuildTools.
No matching distribution found for docling / Requires-Python >=3.10
Pourquoi cela arrive : Docling nécessite Python 3.10 ou supérieur ; Python 3.9 et antérieurs ne sont pas pris en charge.
Correctif rapide : Créez un environnement avec Python 3.10+ et réinstallez.
Correctif recommandé : Utilisez un environnement virtuel ou uv : uv venv --python 3.12 puis uv add docling.
uv venv --python 3.12
Quand cela ne s'applique pas : Les versions très récentes de Python peuvent être en retard jusqu'à la publication des wheels ; voir la matrice officielle.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Failed building wheel for docling-parse / ERROR: Failed to build installable wheels for some pyproject.toml based projects
Pourquoi cela arrive : Aucun wheel précompilé n'existe pour votre plateforme ou votre Python (par exemple macOS antérieur à 13, Alpine/Termux, architectures exotiques ou un Python très récent), donc pip tente de compiler depuis les sources.
Correctif rapide : Utilisez une plateforme et un Python pris en charge (3.10-3.12) et installez avec uv pour récupérer des wheels.
Correctif recommandé : Sous macOS, utilisez macOS 13+ (Apple Silicon) ; sous Linux, préférez une distribution x86_64/arm64 courante ou le conteneur officiel. Épinglez une version de docling dont les wheels correspondent, ou compilez avec une chaîne C++ complète.
uv venv --python 3.12 && uv add docling
Quand cela ne s'applique pas : Le 32 bits, musl/Alpine sans dépendances de compilation et certains systèmes ARM ne sont pas pris en charge officiellement.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
ImportError: libGL.so.1: cannot open shared object file: No such file or directory / ModuleNotFoundError: No module named 'cv2'
Pourquoi cela arrive : opencv-python (avec l'interface OpenGL) est installé dans un environnement sans écran comme Docker ou une VM distante, ou OpenCV est totalement absent dans un environnement neuf.
Correctif rapide : Forcez la version headless d'OpenCV.
Correctif recommandé : pip uninstall -y opencv-python opencv-python-headless && pip install --no-cache-dir opencv-python-headless. Sinon, installez la bibliothèque système : apt-get install libgl1 (Debian) ou 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)
Pourquoi cela arrive : Sous Python 3.13, Docling a besoin de numpy 2.x, mais d'anciens pins LangChain ou autres imposent numpy 1.x ; le résolveur ne peut pas satisfaire les deux.
Correctif rapide : Excluez Python 3.13 de la plage Python de votre projet.
Correctif recommandé : Définissez python = ">=3.10,<3.13" dans pyproject.toml, ou mettez à jour docling-ibm-models>=2.0.7 et deepsearch-glm>=0.26.2. Pour des besoins mixtes, utilisez des marqueurs numpy par version de Python.
python = ">=3.10,<3.13"
Quand cela ne s'applique pas : Certains paquets tiers n'ont pas encore de wheels pour Python 3.13.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Could not find a version that satisfies the requirement torch / no matching distribution found for torch
Pourquoi cela arrive : PyTorch a cessé de publier des wheels macOS x86_64 (Intel) après la 2.2.2, et la 2.2.2 exige numpy 1.x et Python 3.12 ou inférieur.
Correctif rapide : Installez l'extra mac_intel, qui épingle des versions compatibles.
Correctif recommandé : pip install "docling[mac_intel]" (ou uv add torch==2.2.2 torchvision==0.17.2 docling). Gardez numpy<2 et Python 3.12 ou inférieur.
pip install "docling[mac_intel]"
Quand cela ne s'applique pas : Apple Silicon est la valeur par défaut prise en charge ; les Mac Intel nécessitent ce jeu épinglé.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Erreur de certificat SSL au téléchargement des modèles
Installation
URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate>
Pourquoi cela arrive : La liste des certificats de confiance de l'environnement Python est obsolète lors du téléchargement des poids depuis Hugging Face.
Correctif rapide : Mettez à jour certifi.
Correctif recommandé : pip install --upgrade certifi. Si le problème persiste, pointez SSL_CERT_FILE et REQUESTS_CA_BUNDLE vers `python -m certifi`, ou installez pip-system-certs.
pip install --upgrade certifi
Quand cela ne s'applique pas : Derrière un proxy d'entreprise, configurez aussi HTTPS_PROXY et votre autorité racine interne.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
docling: command not found / Docling version: unknown
Pourquoi cela arrive : La mise à jour d'une ancienne installation peut désenregistrer le script de console docling, car le projet a été scindé en docling et docling-slim.
Correctif rapide : Réinstallez le paquet qui fournit la commande.
Correctif recommandé : pip install --force-reinstall docling (ou pip install -U docling docling-slim), puis docling --version. Dans un environnement virtuel, assurez-vous que bin/Scripts est dans le PATH.
pip install --force-reinstall docling
Quand cela ne s'applique pas : uv tool install docling peut échouer pour la même raison ; installez docling-slim[standard].
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Problème de téléchargement ou de cache des modèles
Modèles et cache
OSError / ConnectionError while downloading ds4sd/docling-models / a partial cache blocks later runs
Pourquoi cela arrive : La première conversion PDF télécharge les modèles de mise en page, de tableaux et d'OCR ; un téléchargement échoué ou partiel laisse un cache corrompu.
Correctif rapide : Relancez une fois avec une connexion correcte, ou pré-téléchargez les modèles.
Correctif recommandé : Pré-téléchargez tout avec docling-tools models download --all et pointez DOCLING_CACHE_DIR vers un emplacement inscriptible.
docling-tools models download --all
Quand cela ne s'applique pas : Les machines isolées doivent d'abord copier le cache depuis un hôte connecté.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Les modèles hors ligne sont ignorés (contacte encore Hugging Face)
Modèles et cache
Still tries to reach huggingface.co / FileNotFoundError: Missing .../model.safetensors
Pourquoi cela arrive : Le chemin d'artefacts pointe vers le mauvais dossier, ou la structure des dossiers ne correspond pas à ce qu'attend Docling.
Correctif rapide : Pointez Docling vers le dossier parent qui contient les sous-dossiers de modèles.
Correctif recommandé : Lancez docling-tools models download -o ./models, puis définissez artifacts_path="./models" (chemin absolu dans les conteneurs). Le dossier doit contenir des sous-dossiers comme ds4sd--docling-models avec model.safetensors, config.json et preprocessor_config.json directement à l'intérieur.
docling-tools models download -o ./models
Quand cela ne s'applique pas : Les variables d'environnement ne suffisent pas pour l'API Python ; passez artifacts_path explicitement.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
403 ou limite de débit au téléchargement des modèles
Modèles et cache
403 Client Error / rate limit exceeded / HTTPError while downloading model weights
Pourquoi cela arrive : Des dépôts restreints, des limites de débit ou un proxy d'entreprise bloquent les téléchargements anonymes Hugging Face.
Correctif rapide : Authentifiez-vous avec un token Hugging Face.
Correctif recommandé : export HF_TOKEN=your_token (ou huggingface-cli login) et augmentez les délais avec HF_HUB_ETAG_TIMEOUT et HF_HUB_DOWNLOAD_TIMEOUT. Derrière un proxy, définissez HTTPS_PROXY.
export HF_TOKEN=your_token
Quand cela ne s'applique pas : Certains modèles exigent d'accepter une licence sur Hugging Face au préalable.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Pourquoi cela arrive : Hugging Face tente de créer des entrées de cache ou des liens symboliques dans un montage en lecture seule lors du chargement de modèles locaux.
Correctif rapide : Pointez le cache vers un chemin inscriptible.
Correctif recommandé : Définissez HF_HOME et HF_HUB_CACHE vers un dossier inscriptible et HF_HUB_OFFLINE=1 une fois tous les modèles présents ; montez le dossier de modèles comme données, pas comme cache Hugging Face.
export HF_HUB_CACHE=/tmp/hf-cache
Quand cela ne s'applique pas : HF_HUB_OFFLINE=1 désactive tout accès réseau ; assurez-vous d'avoir tous les modèles avant.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
ModuleNotFoundError: No module named 'tesserocr' / OCR engine import fails
Pourquoi cela arrive : Certains moteurs OCR nécessitent des binaires système (par exemple Tesseract) que pip ne peut pas installer.
Correctif rapide : Utilisez RapidOCR ou EasyOCR, qui sont purement Python et plus simples à installer.
Correctif recommandé : pip install "docling[rapidocr]" ou "docling[easyocr]". Pour Tesseract, installez d'abord le binaire système (brew/apt/dnf), puis l'extra.
pip install "docling[rapidocr]"
Quand cela ne s'applique pas : Tesseract nécessite aussi les données de langue ; définissez TESSDATA_PREFIX si des langues manquent.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Pourquoi cela arrive : Les images de page rendues sans métadonnées DPI peuvent faire échouer Tesseract, surtout dans les conteneurs.
Correctif rapide : Essayez un autre moteur OCR, ou rendez les pages en images avec un DPI explicite.
Correctif recommandé : Passez à RapidOCR ou EasyOCR, ou pré-rendez avec une densité fixe (ImageMagick : convert -density 216 input.pdf page.png) puis OCRisez l'image.
convert -density 216 input.pdf page.png
Quand cela ne s'applique pas : C'est une bizarrerie propre à Tesseract ; les autres moteurs ne sont pas concernés.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Non-English text comes out garbled or empty / wrong characters
Pourquoi cela arrive : Le moteur OCR utilise par défaut un ensemble limité de langues.
Correctif rapide : Définissez les langues OCR dans les options du pipeline.
Correctif recommandé : pipeline_options.ocr_options.lang = ["fr", "de", "en"] — le moteur choisi doit prendre en charge ces langues et, pour Tesseract, les données doivent être installées.
torch.cuda.is_available() is False / processing stays on the CPU
Pourquoi cela arrive : PyTorch a été installé sans support CUDA, ou aucun GPU et pilote compatibles ne sont disponibles.
Correctif rapide : Vérifiez que torch.cuda.is_available() renvoie True.
Correctif recommandé : Désinstallez les wheels CPU et installez PyTorch avec CUDA pour votre version, puis sélectionnez le périphérique avec --device cuda. Vérifiez avec nvidia-smi.
torch.cuda.OutOfMemoryError: CUDA out of memory. Tried to allocate ...
Pourquoi cela arrive : Les tailles de lot dépassent la VRAM disponible, ou un autre processus occupe la mémoire GPU.
Correctif rapide : Réduisez les tailles de lot et videz le cache.
Correctif recommandé : Réduisez layout_batch_size, ocr_batch_size et table_batch_size, définissez queue_max_size, appelez torch.cuda.empty_cache() entre les documents et traitez moins de fichiers en parallèle.
import torch
torch.cuda.empty_cache()
pipeline_options.ocr_batch_size = 2
Quand cela ne s'applique pas : Les pages très volumineuses peuvent encore dépasser la VRAM ; utilisez le CPU pour ces fichiers.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
CUDA error: no kernel image is available for execution on the device
Pourquoi cela arrive : La compilation CUDA de PyTorch n'inclut pas de noyaux pour la capacité de calcul de votre GPU, fréquent sur les GPU très récents ou avec un pilote ancien.
Correctif rapide : Utilisez une compilation PyTorch ou un conteneur correspondant à votre GPU et votre pilote.
Correctif recommandé : Vérifiez la compatibilité pilote/CUDA, mettez à jour le pilote NVIDIA et utilisez le wheel CUDA adapté (cu128/cu130) ou l'image CUDA docling-serve correspondante. Dans Docker, exposez le GPU avec le NVIDIA Container Toolkit.
nvidia-smi
Quand cela ne s'applique pas : Les GPU très récents peuvent nécessiter une compilation CUDA plus récente que l'image actuelle.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
torch.backends.mps.is_available() is False / inference falls back to CPU
Pourquoi cela arrive : MPS nécessite macOS 12.3+ sur une puce M et une compilation PyTorch avec MPS ; certaines opérations basculent encore sur le CPU.
Correctif rapide : Utilisez device auto pour que Docling choisisse le meilleur périphérique disponible.
Correctif recommandé : Exécutez avec --device mps sur Apple Silicon et mettez à jour macOS et PyTorch ; utilisez auto pour le repli automatique.
docling convert report.pdf --device mps
Quand cela ne s'applique pas : Certains modèles exécutent encore des parties du pipeline sur le CPU.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Pourquoi cela arrive : Les modèles d'OCR et d'enrichissement sont coûteux, surtout sur CPU.
Correctif rapide : Désactivez l'OCR pour les PDF numériques et l'enrichissement inutile.
Correctif recommandé : Utilisez --no-ocr pour les PDF texte, --table-mode fast si la précision le permet, generate_page_images=False, et un GPU quand c'est possible. Ajustez --num-threads à vos cœurs CPU.
docling convert report.pdf --no-ocr --to md
Quand cela ne s'applique pas : Les documents scannés nécessitent réellement l'OCR et ne peuvent pas l'éviter.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Killed / std::bad_alloc / the process is OOM-killed
Pourquoi cela arrive : Les PDF volumineux, riches en images ou en formules, peuvent épuiser la RAM, et le backend docling-parse peut accumuler de la mémoire entre les pages.
Correctif rapide : Traitez le PDF par plages de pages ou découpez-le en fichiers plus petits.
Correctif recommandé : converter.convert("large.pdf", page_range=[1, 100]) ; passez aux backends PyPdfium pour les fichiers très volumineux ; désactivez l'enrichissement ; gardez generate_parsed_pages=False ; exécutez dans un sous-processus et redémarrez entre les fichiers.
docling convert large.pdf --page-range 1-100
Quand cela ne s'applique pas : Le découpage peut casser les titres et les tableaux multi-pages qui chevauchent la limite.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
RAM rises steadily when processing a batch / DoclingLoader leaks memory
Pourquoi cela arrive : Le backend PDF conserve des caches et des références de documents après chaque conversion.
Correctif rapide : Libérez explicitement le backend après chaque fichier.
Correctif recommandé : Appelez result.input._backend.unload() après la conversion, recréez le DocumentConverter tous les quelques fichiers ou utilisez un sous-processus par fichier. Gardez docling, docling-core et docling-parse à jour.
result.input._backend.unload()
Quand cela ne s'applique pas : L'enrichissement des formules a sa propre fuite connue ; isolez-le dans un processus séparé.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
ConversionError: Input document file.pdf is not valid / status FAILURE
Pourquoi cela arrive : Le fichier peut être chiffré, corrompu, protégé par mot de passe ou dans une variante non prise en charge.
Correctif rapide : Essayez un autre fichier d'exemple pour déterminer si le problème vient du document ou de l'installation.
Correctif recommandé : Retirez la protection par mot de passe ou passez --pdf-password ; réparez ou réexportez le fichier ; vérifiez la liste des formats pris en charge et ouvrez un ticket avec un exemple.
docling convert report.pdf --to md
Quand cela ne s'applique pas : Les PDF chiffrés ne sont pas déchiffrés silencieusement ; fournissez une copie non protégée ou le mot de passe.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Pourquoi cela arrive : Les PDF dont les polices intégrées personnalisées n'ont pas de table ToUnicode ne peuvent pas être traduits en caractères réels.
Correctif rapide : Forcez l'OCR pleine page.
Correctif recommandé : Définissez pipeline_options.ocr_options.force_full_page_ocr = True (ou --ocr-mode full_page). Sinon, passez au backend PyPdfium2, qui décode parfois mieux ces polices.
docling convert broken.pdf --ocr-mode full_page
Quand cela ne s'applique pas : L'OCR peut encore manquer des GLYPH dans les tableaux selon la version ; mettez Docling à jour.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
"fi" / "fl" / "ffi" appear with spaces, e.g. "e ffi cient"
Pourquoi cela arrive : Certaines polices PDF associent les glyphes de ligature à des caractères séparés avec des espaces parasites.
Correctif rapide : Mettez à jour Docling, qui normalise les ligatures courantes.
Correctif recommandé : Le Docling moderne nettoie les ligatures à l'étape d'assemblage de page. Si votre PDF casse encore, utilisez l'OCR ou prétraitez la police.
pip install -U docling
Quand cela ne s'applique pas : Les ligatures basées sur des noms de glyphes peuvent encore passer si le backend ne les décode pas.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Images intégrées manquantes dans les fichiers Office
Conversion
Images are missing from DOCX or PPTX output on macOS or Linux
Pourquoi cela arrive : La gestion des images WMF/EMF ne fonctionne que sous Windows avec la bibliothèque d'images par défaut.
Correctif rapide : Convertissez les images ou lancez la conversion sous Windows.
Correctif recommandé : Convertissez les ressources WMF/EMF en PNG/SVG avant la conversion (par exemple avec LibreOffice headless) ou exécutez cette étape sous Windows.
La conversion depuis une URL échoue (403 ou timeout)
Conversion
HTTPError 403/404 or a timeout when converting an URL
Pourquoi cela arrive : Le serveur bloque les requêtes anonymes, l'URL est une page d'atterrissage, ou la connexion expire.
Correctif rapide : Téléchargez d'abord le fichier et passez le chemin local.
Correctif recommandé : En Python, passez des en-têtes personnalisés : converter.convert(url, headers={"User-Agent": "..."}). Vérifiez que l'URL pointe vers un PDF/DOCX et non une page HTML.
docling convert ./downloaded.pdf --to md
Quand cela ne s'applique pas : Certains sites exigent des cookies ou une authentification que Docling ne gère pas.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Wrong table structure / cells merged or columns shifted
Pourquoi cela arrive : Les cellules fusionnées complexes et les tableaux sans bordures sont difficiles, et le mode rapide échange la précision contre la vitesse.
Correctif rapide : Utilisez le mode tableau précis.
Correctif recommandé : Exécutez avec --table-mode accurate. Pour les problèmes de cellules fusionnées de TableFormer V2, essayez do_cell_matching=False ou revenez à V1, et gardez Docling à jour.
docling convert report.pdf --table-mode accurate
Quand cela ne s'applique pas : Aucun analyseur n'est parfait sur tous les tableaux ; une revue manuelle peut être nécessaire.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
A whitespace-aligned table is extracted as prose / the table is missed
Pourquoi cela arrive : Le modèle de mise en page peut manquer les tableaux sans bordures visibles et traiter les colonnes alignées comme du texte normal.
Correctif rapide : Essayez l'OCR forcé ou un autre backend.
Correctif recommandé : Forcez l'OCR, qui peut révéler la grille, passez au backend PyPdfium2 ou augmentez images_scale. Revoyez manuellement les documents critiques.
docling convert report.pdf --ocr-mode full_page
Quand cela ne s'applique pas : Si le modèle de mise en page ne signale jamais la région, le code en aval ne peut pas la récupérer.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Pourquoi cela arrive : Le modèle de mise en page a besoin d'une marge entre le tableau et le bord de page pour les distinguer.
Correctif rapide : Ajoutez une petite marge blanche autour de la page avant la conversion.
Correctif recommandé : Ajoutez environ 40pt de padding gauche/droite au PDF avant la conversion (par exemple avec pypdf) ; une option native page_padding est à l'étude.
python add_padding.py input.pdf
Quand cela ne s'applique pas : Le padding externe peut modifier la mise en page de certains documents.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
docling-serve does not start / connection refused on port 5001
Pourquoi cela arrive : Un conflit de ports, un extra UI manquant, ou un conteneur nécessitant un autre point d'entrée.
Correctif rapide : Lancez le serveur avec l'extra UI et vérifiez que le port est libre.
Correctif recommandé : pip install "docling-serve[ui]" && docling-serve run --enable-ui, ou utilisez l'image officielle. Modifiez l'adresse ou le port avec UVICORN_HOST/UVICORN_PORT.
docling-serve run --enable-ui
Quand cela ne s'applique pas : Le déploiement avancé (mise à l'échelle, auth) sort du cadre ; voir la doc officielle.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
GET /ready returns 503 / requests time out while models load
Pourquoi cela arrive : L'endpoint /ready reste en 503 tant que les modèles ne sont pas chargés, et avec le moteur RQ tant que Redis n'est pas joignable.
Correctif rapide : Attendez l'état prêt avant d'envoyer du trafic.
Correctif recommandé : Configurez startupProbe et readinessProbe sur /ready et une livenessProbe sur /health, et préchargez les modèles avec DOCLING_SERVE_ARTIFACTS_PATH pour raccourcir le démarrage.
curl -i http://localhost:5001/ready
Quand cela ne s'applique pas : Avec le moteur RQ, /ready exige aussi la connectivité Redis.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
CUDA error: no kernel image is available / the container runs on CPU despite --gpus
Pourquoi cela arrive : Le conteneur n'a pas accès au GPU, ou le tag d'image CUDA et le pilote hôte ne correspondent pas.
Correctif rapide : Exposez le GPU avec le NVIDIA Container Toolkit.
Correctif recommandé : Installez et mettez à jour nvidia-container-toolkit, configurez le runtime nvidia et demandez le GPU (docker run --gpus all, ou devices count: all dans Compose). Utilisez le tag CUDA correspondant à votre pilote.
docker run --gpus all -p 5001:5001 quay.io/docling-project/docling-serve-cu128
Quand cela ne s'applique pas : Certains GPU très récents nécessitent une image CUDA plus récente que celle publiée.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
The MCP server is not listed in the client / no tools appear / the server exits immediately
Pourquoi cela arrive : La configuration du client pointe vers la mauvaise commande, le paquet est indisponible, ou le transport est incorrect.
Correctif rapide : Lancez le serveur une fois manuellement pour vérifier qu'il fonctionne.
Correctif recommandé : uvx --from=docling-mcp docling-mcp-server et ajoutez le JSON correspondant à claude_desktop_config.json (ou mcp.json). Redémarrez le client et ajoutez --transport stdio si nécessaire.
uvx --from=docling-mcp docling-mcp-server
Quand cela ne s'applique pas : L'emplacement des fichiers de configuration varie selon le client ; consultez sa documentation.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
[Errno 2] No such file or directory / the MCP client times out on a cold start
Pourquoi cela arrive : Le serveur MCP ne voit pas le système de fichiers du client, ou la première conversion est lente pendant le chargement des modèles.
Correctif rapide : Utilisez un dossier partagé, ou passez en mode distant via docling-serve.
Correctif recommandé : Définissez DOCLING_MCP_CONVERSION_MODE=remote avec DOCLING_MCP_SERVICE_URL, ou montez un dossier partagé lisible par les deux processus. Préchauffez le cache de modèles pour éviter les expirations à froid.
export DOCLING_MCP_CONVERSION_MODE=remote
Quand cela ne s'applique pas : Les clients web ne partagent pas de système de fichiers avec un serveur MCP local.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
Avertissement de longueur de tokens du HybridChunker
RAG et découpage
Token indices sequence length is longer than the specified maximum sequence length for this model (531 > 512)
Pourquoi cela arrive : Transformers avertit pendant que le chunker compte les tokens d'une séquence trop longue puis la découpe ; c'est une fausse alerte.
Correctif rapide : Ignorez l'avertissement.
Correctif recommandé : Confirmez les tailles réelles en sérialisant chaque chunk et en comptant les tokens avec le même tokenizer.
for c in chunker.chunk(doc):
print(len(tokenizer.tokenize(chunker.serialize(chunk=c))))
pip install -U docling-core
Quand cela ne s'applique pas : Si un chunk réel dépasse la limite du modèle, alignez le tokenizer du chunker sur votre modèle d'embedding.
Vérifié avec Docling v2.129.0 · Dernière vérification 2026-09-22
La plupart des problèmes Docling viennent d'une version obsolète, d'un extra optionnel manquant ou d'un document difficile. Suivez ces étapes avant tout.
Identifiez le texte de l'erreur. Cherchez dans les cartes ci-dessus ; le message exact figure souvent comme symptôme.
Mettez d'abord à jour. Beaucoup de problèmes sont déjà corrigés : pip install -U docling docling-core docling-parse.
Reproduisez sur un fichier simple. Si un petit PDF ou DOCX simple fonctionne, le problème vient en général du document, pas de l'installation.
Changez une seule chose. Essayez --pdf-backend pypdfium2, --ocr-mode full_page ou --table-mode fast.
Réduisez le périmètre. Utilisez --page-range, désactivez l'enrichissement et convertissez un seul fichier.
Rassemblez les détails avant de signaler (carte suivante).
2
?tape 2
Rassemblez votre environnement
Copiez ces commandes pour avoir les versions et les informations de périphérique sous la main en cas d'échec.
Indiquez la commande exacte et la trace complète.
Joignez ou décrivez un document d'exemple minimal si possible.
Précisez votre OS, la version de Python et si vous utilisez Docker.
Ajoutez -vv pour des logs de conversion détaillés.
Un bon rapport permet une correction rapide. Incluez tout ce qui est nécessaire pour reproduire.
Cherchez d'abord dans les issues existantes pour éviter les doublons.
Indiquez les versions de Docling, docling-core et Python.
Collez la commande exacte et la trace complète.
Joignez un document d'exemple minimal s'il n'est pas confidentiel.
Posez les questions d'usage dans les discussions, pas le tracker.
11
?tape 11
Questions fréquentes
Quelle erreur corriger en premier ?
Commencez par les erreurs d'installation et de modèles. Rien d'autre ne fonctionne tant que Docling n'est pas installé et ne peut pas charger ses modèles.
J'ai mis à jour et quelque chose s'est cassé. Que faire ?
Épinglez la version précédente avec pip install docling==<version> pour vous débloquer, puis signalez la régression avec un exemple.
Mon document est-il envoyé quelque part ?
Non. Docling s'exécute en local et n'envoie aucune donnée de document. Le seul accès réseau est le téléchargement des poids.
Dois-je découper les gros PDF ?
Seulement si vous atteignez les limites de mémoire. Essayez d'abord --page-range, puis le découpage, en acceptant une perte de structure entre les pages.
Pourquoi mes tableaux sont-ils mal extraits ?
Les cellules fusionnées complexes et les tableaux sans bordures sont difficiles. Utilisez le mode précis, essayez do_cell_matching=False ou TableFormer V1 et relisez les tableaux critiques.
La CLI fonctionne mais pas Python. Pourquoi ?
Utilisez le même environnement virtuel pour les deux et passez les options via PdfFormatOption pour qu'elles atteignent le pipeline.
Où obtenir plus d'aide ?
Cherchez dans les issues et discussions GitHub officielles en indiquant vos versions, la commande et la trace.