Docling トラブルシューティング

error: Microsoft Visual C++ 14.0 or greater is required / Failed building wheel for docling-parse

原因: 一部のオプション依存関係はネイティブの C++ または Rust 拡張をコンパイルするため、既定で存在しないコンパイラーが必要です。

簡単な対処: pip ではなく Astral uv を使うとビルド済みホイールを利用できます: uv add docling。

推奨される対処: どうしても pip を使う場合は、Microsoft Visual C++ Build Tools (14.0+) と 64 ビット Python をインストールして再試行してください。非対応 OS や Python では Python 3.10〜3.12 かコンテナーを使用します。

当てはまらない場合: OS と Python に対応するホイールがない場合は、コンパイラーが必要なことがあります。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · インストールガイド

Microsoft Visual C++ 14.0 is required. Get it with Microsoft C++ Build Tools

原因: pip がソースからネイティブ拡張をビルドしようとしていますが、MSVC ツールチェーンが見つかりません。

簡単な対処: ビルド済みホイールを解決しコンパイラーを完全に回避する uv を推奨します。

推奨される対処: それ以外の場合は Build Tools を「C++ によるデスクトップ開発」ワークロード付きでインストールします: winget install Microsoft.VisualStudio.2022.BuildTools。

当てはまらない場合: 主に tesserocr や fasttext などのオプション拡張に該当し、本体は通常ホイールが提供されます。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · インストールガイド

No matching distribution found for docling / Requires-Python >=3.10

原因: Docling は Python 3.10 以降が必要で、3.9 以前は対応していません。

簡単な対処: Python 3.10+ の環境を作成して再インストールします。

推奨される対処: 仮想環境か uv を使います: uv venv --python 3.12 の後に uv add docling。

当てはまらない場合: 非常に新しい Python はホイールが揃うまで遅れることがあります。公式の対応表を確認してください。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · インストールガイド

Failed building wheel for docling-parse / ERROR: Failed to build installable wheels for some pyproject.toml based projects

原因: お使いのプラットフォームや Python 用のビルド済みホイールがないため (macOS 13 未満、Alpine/Termux、特殊なアーキテクチャ、非常に新しい Python など)、pip がソースからコンパイルしようとします。

簡単な対処: 対応プラットフォームと Python 3.10〜3.12 を使い、uv でインストールしてホイールを取得します。

推奨される対処: macOS では macOS 13+ (Apple Silicon) を使用。Linux では一般的な x86_64/arm64 ディストリビューションか公式コンテナーを推奨。ホイールが合う Docling のバージョンを固定するか、完全な C++ ツールチェーンでビルドします。

当てはまらない場合: 32 ビット、ビルド依存のない musl/Alpine、一部の ARM システムは公式には非対応です。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · インストールガイド

ImportError: libGL.so.1: cannot open shared object file: No such file or directory / ModuleNotFoundError: No module named 'cv2'

原因: OpenGL UI 付きの opencv-python が Docker やリモート VM などのヘッドレス環境に入っているか、新しい環境で OpenCV が完全に欠けています。

簡単な対処: ヘッドレス版の OpenCV を強制します。

推奨される対処: pip uninstall -y opencv-python opencv-python-headless && pip install --no-cache-dir opencv-python-headless。またはシステムライブラリを導入: apt-get install libgl1 (Debian) または dnf install mesa-libGL (RHEL)。

当てはまらない場合: OpenCV の GUI ウィンドウが必要な場合は、ヘッドレス化ではなくシステムの libGL をインストールしてください。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 公式 FAQ

version solving failed ... depends on numpy (>=2.0.2,<3.0.0) and docling requires numpy (>=1.26.4,<2.0.0)

原因: Python 3.13 では Docling は numpy 2.x を必要としますが、古い LangChain などの固定が numpy 1.x を強制し、解決できません。

簡単な対処: プロジェクトの Python 範囲から 3.13 を除外します。

推奨される対処: pyproject.toml に python = ">=3.10,<3.13" を設定するか、docling-ibm-models>=2.0.7 と deepsearch-glm>=0.26.2 に更新します。混在時は Python バージョン別の numpy マーカーを使います。

当てはまらない場合: 一部のサードパーティ製パッケージはまだ Python 3.13 用ホイールがありません。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 公式 FAQ

Could not find a version that satisfies the requirement torch / no matching distribution found for torch

原因: PyTorch は 2.2.2 以降 macOS x86_64 (Intel) のホイールを提供しておらず、2.2.2 は numpy 1.x と Python 3.12 以下を必要とします。

簡単な対処: 互換バージョンを固定する mac_intel エクストラをインストールします。

推奨される対処: pip install "docling[mac_intel]" (または uv add torch==2.2.2 torchvision==0.17.2 docling)。numpy<2 と Python 3.12 以下を維持します。

当てはまらない場合: Apple Silicon が標準の対応環境で、Intel Mac は固定スタックが必要です。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · macOS へのインストール

URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate>

原因: Hugging Face から重みを取得する際に、Python 環境の信頼済み証明書リストが古くなっています。

簡単な対処: certifi を更新します。

推奨される対処: pip install --upgrade certifi。改善しない場合は SSL_CERT_FILE と REQUESTS_CA_BUNDLE を `python -m certifi` に設定するか、pip-system-certs を導入します。

当てはまらない場合: 社内プロキシでは HTTPS_PROXY と社内ルート CA も設定してください。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 公式 FAQ

docling: command not found / Docling version: unknown

原因: 古いインストールをアップグレードすると、プロジェクトが docling と docling-slim に分割されたため docling コンソールスクリプトが登録解除されることがあります。

簡単な対処: コマンドを提供するパッケージを再インストールします。

推奨される対処: pip install --force-reinstall docling (または pip install -U docling docling-slim) の後に docling --version。仮想環境では bin/Scripts が PATH にあることを確認します。

当てはまらない場合: uv tool install docling も同じ理由で失敗することがあり、docling-slim[standard] を使います。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · インストールガイド

'pip' is not recognized as an internal or external command

原因: 埋め込み Python や既定の Windows インストールでは Python と Scripts が PATH に追加されません。

簡単な対処: 埋め込み Python ではなく通常の Python と仮想環境を使います。

推奨される対処: python.org から Python 3.12 を「Add python.exe to PATH」をチェックしてインストールし、venv を作成 (py -m venv .venv)、有効化して pip install docling。pip がない場合は py -m ensurepip --upgrade。

当てはまらない場合: 埋め込み Python はインストール型コンソールスクリプト向けではなく、Docling には推奨されません。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · Windows へのインストール

OSError / ConnectionError while downloading ds4sd/docling-models / a partial cache blocks later runs

原因: 最初の PDF 変換でレイアウト・表・OCR モデルをダウンロードし、失敗や途中終了で壊れたキャッシュが残ります。

簡単な対処: 接続を確認して一度再実行するか、モデルを事前にダウンロードします。

推奨される対処: docling-tools models download --all で全モデルを事前取得し、DOCLING_CACHE_DIR を書き込み可能な場所に設定します。

当てはまらない場合: エアギャップ環境では、接続済みホストからキャッシュを先にコピーする必要があります。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · オフライン / エアギャップ

Still tries to reach huggingface.co / FileNotFoundError: Missing .../model.safetensors

原因: artifacts_path が誤ったディレクトリを指しているか、フォルダー構造が Docling の期待と一致していません。

簡単な対処: モデルのサブフォルダーを含む親フォルダーを指定します。

推奨される対処: docling-tools models download -o ./models を実行し、artifacts_path="./models" を設定します (コンテナーでは絶対パス)。ds4sd--docling-models などのサブフォルダーに model.safetensors、config.json、preprocessor_config.json が直接入っている必要があります。

当てはまらない場合: Python API では環境変数だけでは不十分で、artifacts_path を明示的に渡す必要があります。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · オフライン / エアギャップ

Models appear in both ./models and ~/.cache/huggingface

原因: Hugging Face ライブラリは指定ディレクトリとは別に独自のグローバルキャッシュを保持します。

簡単な対処: HF_HOME を設定してダウンロード先を 1 か所にまとめます。

推奨される対処: 実行前に export HF_HOME=/your/cache (または HF_HUB_CACHE) を設定し、同じフォルダーを artifacts_path に渡します。

当てはまらない場合: Docling は指定パスを尊重しますが、Hugging Face ライブラリは独自キャッシュを作成します。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · オフライン / エアギャップ

403 Client Error / rate limit exceeded / HTTPError while downloading model weights

原因: 制限付きリポジトリ、レート制限、社内プロキシが匿名の Hugging Face ダウンロードをブロックします。

簡単な対処: Hugging Face トークンで認証します。

推奨される対処: export HF_TOKEN=your_token (または huggingface-cli login) を設定し、HF_HUB_ETAG_TIMEOUT と HF_HUB_DOWNLOAD_TIMEOUT でタイムアウトを延ばします。プロキシ環境では HTTPS_PROXY を設定します。

当てはまらない場合: 一部のモデルは事前に Hugging Face でライセンス同意が必要です。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · オフライン / エアギャップ

OSError: [Errno 30] Read-only file system: '/models/models--ds4sd--docling-models/snapshots/...'

原因: ローカルモデル読み込み時に Hugging Face が読み取り専用マウントへキャッシュやシンボリックリンクを作成しようとします。

簡単な対処: キャッシュを書き込み可能なパスに変更します。

推奨される対処: HF_HOME と HF_HUB_CACHE を書き込み可能なディレクトリに設定し、全モデルが揃ったら HF_HUB_OFFLINE=1 を設定します。モデルディレクトリは HF キャッシュではなくデータとしてマウントします。

当てはまらない場合: HF_HUB_OFFLINE=1 はすべてのネットワークアクセスを無効化するため、事前に全モデルを用意してください。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · オフライン / エアギャップ

ModuleNotFoundError: No module named 'tesserocr' / OCR engine import fails

原因: 一部の OCR エンジンは pip では導入できないシステムバイナリ (例: Tesseract) を必要とします。

簡単な対処: 純 Python で導入が容易な RapidOCR または EasyOCR を使います。

推奨される対処: pip install "docling[rapidocr]" または "docling[easyocr]"。Tesseract は先にシステムバイナリ (brew/apt/dnf) を入れ、その後 extra を導入します。

当てはまらない場合: Tesseract は言語データも必要で、言語が欠けている場合は TESSDATA_PREFIX を設定します。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · OCR エンジンを比較

RapidOCR is not installed. Please install it via 'pip install rapidocr_onnxruntime' to use this OCR engine

原因: RapidOCR はオプションのエンジンで、基本インストールには含まれません。

簡単な対処: rapidocr extra をインストールします。

推奨される対処: pip install "docling[rapidocr]" (または pip install rapidocr onnxruntime)。

当てはまらない場合: RapidOCR の GPU 加速は限定的で、既定では CPU で動作します。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · OCR エンジンを比較

Error: Failed loading language 'deu' / TESSDATA_PREFIX is not set

原因: Tesseract には .traineddata ファイルと、tessdata フォルダーを指す正しい TESSDATA_PREFIX が必要です。

簡単な対処: 言語パックをインストールし、TESSDATA_PREFIX を設定します (末尾はスラッシュ)。

推奨される対処: apt-get install tesseract-ocr-eng tesseract-ocr-deu (Debian) の後に export TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata/。ocr_options.lang を導入した言語に設定します。

当てはまらない場合: コンテナーには英語のみが含まれることが多く、追加言語は独自イメージで導入します。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · OCR エンジンを比較

Invalid resolution 0 dpi. Using 70 instead. / tesseract OCR failed

原因: DPI メタデータなしでレンダリングされたページ画像は、特にコンテナーで Tesseract を失敗させることがあります。

簡単な対処: 別の OCR エンジンを試すか、明示的な DPI でページを画像化してから処理します。

推奨される対処: RapidOCR か EasyOCR に切り替えるか、固定密度で事前レンダリング (ImageMagick: convert -density 216 input.pdf page.png) して画像を OCR します。

当てはまらない場合: Tesseract 固有の挙動で、他のエンジンには影響しません。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · OCR エンジンを比較

Non-English text comes out garbled or empty / wrong characters

原因: OCR エンジンは既定で限られた言語セットを使用します。

簡単な対処: パイプラインオプションで OCR 言語を設定します。

推奨される対処: pipeline_options.ocr_options.lang = ["fr", "de", "en"] — 選択したエンジンがそれらの言語に対応している必要があり、Tesseract では言語データの導入も必要です。

当てはまらない場合: エンジンごに対応言語が異なります。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · OCR エンジンを比較

torch.cuda.is_available() is False / processing stays on the CPU

原因: PyTorch が CUDA 対応なしでインストールされたか、互換 GPU とドライバーがありません。

簡単な対処: torch.cuda.is_available() が True を返すか確認します。

推奨される対処: CPU 版ホイールを削除し、CUDA バージョンに合う CUDA 対応 PyTorch をインストールして --device cuda を指定します。nvidia-smi で確認します。

当てはまらない場合: Apple Silicon は MPS (--device mps) を使い CUDA ではありません。一部の OCR エンジンは CPU 専用です。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · コンフィグジェネレーター

torch.cuda.OutOfMemoryError: CUDA out of memory. Tried to allocate ...

原因: バッチサイズが VRAM を超えているか、別プロセスが GPU メモリを保持しています。

簡単な対処: バッチサイズを下げ、キャッシュを解放します。

推奨される対処: layout_batch_size、ocr_batch_size、table_batch_size を下げ、queue_max_size を設定し、文書間で torch.cuda.empty_cache() を呼び、並列数を減らします。

import torch
torch.cuda.empty_cache()

当てはまらない場合: 非常に大きなページは VRAM を超えることがあり、その場合は CPU を使います。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 技術リファレンス

CUDA error: no kernel image is available for execution on the device

原因: PyTorch の CUDA ビルドに、お使いの GPU の Compute Capability 向けカーネルが含まれていません。新しい GPU や古いドライバーでよく起こります。

簡単な対処: GPU とドライバーに合う PyTorch またはコンテナーを使います。

推奨される対処: ドライバー/CUDA の互換性を確認し、NVIDIA ドライバーを更新し、対応する CUDA ホイール (cu128/cu130) か対応する docling-serve CUDA イメージを使います。Docker では NVIDIA Container Toolkit で GPU を公開します。

当てはまらない場合: 最新の GPU は現在のイメージより新しい CUDA ビルドが必要なことがあります。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · Docker でのインストール

flash-attn fails to build / ImportError: cannot import name 'flash_attn'

原因: Flash Attention 2 は Ampere 以降の GPU、CUDA 11.8+、PyTorch 2.0+ を必要とし、ソースからのビルドが困難です。

簡単な対処: 不要であれば無効化します。

推奨される対処: accelerator_options = AcceleratorOptions(cuda_use_flash_attention2=False) を設定するか、FLASH_ATTENTION_SKIP_CUDA_BUILD=TRUE pip install flash-attn で導入します。

当てはまらない場合: Ampere 以前の GPU や Apple Silicon では非対応です。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 公式 FAQ

torch.backends.mps.is_available() is False / inference falls back to CPU

原因: MPS は M シリーズの macOS 12.3+ と MPS 対応 PyTorch ビルドを必要とし、一部の演算は CPU にフォールバックします。

簡単な対処: device auto を使い、Docling に最適なデバイスを選ばせます。

推奨される対処: Apple Silicon では --device mps で実行し、macOS と PyTorch を更新します。自動フォールバックには auto を使います。

当てはまらない場合: 一部のモデルはパイプラインの一部を CPU で実行します。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · macOS へのインストール

A single document takes minutes / high CPU usage

原因: OCR とエンリッチメントのモデルは高コストで、特に CPU で顕著です。

簡単な対処: デジタル PDF では OCR を無効化し、不要なエンリッチメントを切ります。

推奨される対処: テキスト PDF には --no-ocr、精度が許せば --table-mode fast、generate_page_images=False を指定し、可能なら GPU を使います。--num-threads を CPU コア数に合わせます。

当てはまらない場合: スキャン文書は実際に OCR が必要で省略できません。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · コンフィグジェネレーター

Killed / std::bad_alloc / the process is OOM-killed

原因: 画像や数式の多い大きな PDF は RAM を枯渇させ、docling-parse バックエンドはページ間でメモリを蓄積することがあります。

簡単な対処: ページ範囲で処理するか、より小さなファイルに分割します。

推奨される対処: converter.convert("large.pdf", page_range=[1, 100])。非常に大きなファイルは PyPdfium バックエンドに切り替え、エンリッチメントを無効化し、generate_parsed_pages=False を維持し、サブプロセスでファイルごとに再起動します。

当てはまらない場合: 分割は境界をまたぐ見出しや複数ページの表を壊すことがあります。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 技術リファレンス

RAM rises steadily when processing a batch / DoclingLoader leaks memory

原因: PDF バックエンドは変換ごとにキャッシュと文書参照を保持します。

簡単な対処: ファイルごとにバックエンドを明示的に解放します。

推奨される対処: 変換後に result.input._backend.unload() を呼ぶか、数ファイルごとに DocumentConverter を再作成するか、ファイルごとにサブプロセスを使います。docling、docling-core、docling-parse を最新に保ちます。

当てはまらない場合: 数式エンリッチメントには既知のリークがあり、別プロセスに分離してください。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 技術リファレンス

ConversionError: Input document file.pdf is not valid / status FAILURE

原因: ファイルが暗号化、破損、パスワード保護、または非対応の形式である可能性があります。

簡単な対処: 別のサンプルファイルで、原因が文書かセットアップかを切り分けます。

推奨される対処: パスワード保護を解除するか --pdf-password を渡します。ファイルを修復・再出力し、対応フォーマット一覧を確認してサンプル付きで issue を立てます。

当てはまらない場合: 暗号化 PDF は自動で復号されないため、保護なしのコピーかパスワードを用意します。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 対応フォーマット

PdfiumError: Failed to load document (PDFium: Incorrect password error) / ConversionError with cause PdfiumError

原因: PDF が暗号化されており、パスワードが指定されていません。

簡単な対処: 文書のパスワードを指定します。

推奨される対処: CLI: docling convert secret.pdf --pdf-password 'secret'。Python: PdfFormatOption(backend_options=...) 経由で PdfBackendOptions(password=SecretStr('secret')) を渡します。

当てはまらない場合: パスワード対応には docling-parse v4 または PyPdfium2 バックエンドが必要です。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 対応フォーマット

GLYPH<38> GLYPH<39> ... / /gid00020 / unreadable characters

原因: ToUnicode マップを持たないカスタム埋め込みフォントの PDF は実文字に変換できません。

簡単な対処: 全ページ OCR を強制します。

推奨される対処: pipeline_options.ocr_options.force_full_page_ocr = True (または --ocr-mode full_page) を設定します。または、こうしたフォントをより良く復号できる PyPdfium2 バックエンドに切り替えます。

当てはまらない場合: バージョンによっては表内の GLYPH が残ることがあるため、Docling を更新してください。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · OCR エンジンを比較

"fi" / "fl" / "ffi" appear with spaces, e.g. "e ffi cient"

原因: 一部の PDF フォントは合字グリフを余分な空白付きの別文字に割り当てます。

簡単な対処: 一般的な合字を正規化する Docling に更新します。

推奨される対処: 最近の Docling はページ組み立て段階で合字を処理します。それでも壊れる場合は OCR を使うかフォントを前処理します。

当てはまらない場合: グリフ名ベースの合字はバックエンドが復号できないと残ることがあります。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 技術リファレンス

Images are missing from DOCX or PPTX output on macOS or Linux

原因: WMF/EMF 画像の処理は既定の画像ライブラリでは Windows でのみ動作します。

簡単な対処: 画像を変換するか、Windows で変換を実行します。

推奨される対処: 変換前に WMF/EMF を PNG/SVG に変換するか (例: LibreOffice headless)、その手順を Windows で実行します。

当てはまらない場合: 影響は WMF/EMF 画像のみで、他の画像形式は通常どおり変換されます。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 対応フォーマット

HTTPError 403/404 or a timeout when converting an URL

原因: サーバーが匿名リクエストを拒否するか、URL がランディングページか、接続がタイムアウトしています。

簡単な対処: 先にファイルをダウンロードし、ローカルパスを渡します。

推奨される対処: Python では独自ヘッダーを渡します: converter.convert(url, headers={"User-Agent": "..."})。URL が HTML ではなく PDF/DOCX を指すことを確認します。

当てはまらない場合: 一部のサイトは Cookie や認証を要求し、Docling では処理できません。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 対応フォーマット

IndexError: list index out of range in md_backend.py

原因: Markdown 内の空のリスト項目 (「-」だけの行) が古いバックエンドを失敗させました。v2.18 で修正済みです。

簡単な対処: Docling を更新します。

推奨される対処: pip install -U docling。回避策として Markdown から空のリストマーカーを削除します。

当てはまらない場合: 古いバージョンの Markdown バックエンドのみに影響します。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 対応フォーマット

convert_all raises at the first invalid document

原因: 既定の raises_on_error=True は最初の失敗でバッチを中断します。

簡単な対処: raises_on_error=False を設定し各結果を確認します。

推奨される対処: for res in converter.convert_all(files, raises_on_error=False): res.status と res.errors を確認しファイルごとに判断します。

当てはまらない場合: PARTIAL_SUCCESS と FAILURE の結果は自分で処理する必要があります。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 技術リファレンス

Wrong table structure / cells merged or columns shifted

原因: 複雑な結合セルや罫線のない表は難しく、fast モードは速度と引き換えに精度を下げます。

簡単な対処: 正確な表モードを使います。

推奨される対処: --table-mode accurate で実行します。TableFormer V2 の結合セル問題では do_cell_matching=False を試すか V1 に戻し、Docling を最新に保ちます。

当てはまらない場合: すべての表で完璧なパーサーはなく、手動確認が必要な場合があります。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · コンフィグジェネレーター

Table structure is detected but all cell text values are empty

原因: 2.78.0 の TableFormer V2 のリグレッションでセルが空になりました。

簡単な対処: Docling を更新します。

推奨される対処: pip install -U docling — 空セルのリグレッションは 2.78.0 以降のリリースで修正されました。

当てはまらない場合: 影響を受けるバージョンの TableFormer V2 のみに該当します。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · コンフィグジェネレーター

A whitespace-aligned table is extracted as prose / the table is missed

原因: レイアウトモデルは罫線のない表を見落とし、整列した列を通常のテキストとして扱うことがあります。

簡単な対処: 強制 OCR や別バックエンドを試します。

推奨される対処: OCR を強制するとグリッドが現れることがあります。PyPdfium2 バックエンドに切り替えるか images_scale を上げます。重要な文書は手動で確認します。

当てはまらない場合: レイアウトモデルが領域を検出しなければ、後段の処理では復元できません。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · OCR エンジンを比較

Full-page or edge-to-edge tables are not detected

原因: レイアウトモデルは表とページ境界を区別するために余白を必要とします。

簡単な対処: 変換前にページ周囲に小さな白い余白を追加します。

推奨される対処: 変換前に PDF へ左右約 40pt のパディングを追加します (例: pypdf)。ネイティブの page_padding オプションは上流で検討中です。

当てはまらない場合: 外部パディングは一部の文書のレイアウトを変えることがあります。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 対応フォーマット

docling-serve does not start / connection refused on port 5001

原因: ポート競合、UI extra の欠如、または別のエントリポイントが必要なコンテナーが原因です。

簡単な対処: UI extra 付きでサーバーを起動し、ポートが空いていることを確認します。

推奨される対処: pip install "docling-serve[ui]" && docling-serve run --enable-ui、または公式コンテナーイメージを使います。UVICORN_HOST/UVICORN_PORT でバインド先やポートを変更できます。

当てはまらない場合: 高度なデプロイ (スケーリング、認証) は範囲外です。公式ドキュメントを参照してください。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · Docker でのインストール

GET /ready returns 503 / requests time out while models load

原因: /ready エンドポイントはモデルが読み込まれるまで 503 を返し、RQ エンジンでは Redis 到達可能になるまで 503 です。

簡単な対処: トラフィックを送る前に準備完了を待ちます。

推奨される対処: /ready に startupProbe と readinessProbe、/health に livenessProbe を設定し、DOCLING_SERVE_ARTIFACTS_PATH でモデルを事前ロードして起動を短縮します。

当てはまらない場合: RQ エンジンでは /ready は Redis 接続も必要とします。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · Docker でのインストール

CUDA error: no kernel image is available / the container runs on CPU despite --gpus

原因: コンテナーに GPU アクセスがないか、CUDA イメージタグとホストドライバーが一致していません。

簡単な対処: NVIDIA Container Toolkit で GPU を公開します。

推奨される対処: nvidia-container-toolkit をインストール・更新し、nvidia ランタイムを構成し、GPU を要求します (docker run --gpus all、Compose では devices count: all)。ドライバーに合う CUDA イメージタグを使います。

当てはまらない場合: 最新の GPU は公開済みより新しい CUDA イメージを要することがあります。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · Docker でのインストール

The MCP server is not listed in the client / no tools appear / the server exits immediately

原因: クライアント設定が誤ったコマンドを指すか、パッケージが利用できないか、トランスポートが誤っています。

簡単な対処: まず手動でサーバーを一度起動して動作確認します。

推奨される対処: uvx --from=docling-mcp docling-mcp-server を実行し、対応する JSON を claude_desktop_config.json (または mcp.json) に追加します。クライアントを再起動し、必要なら --transport stdio を加えます。

当てはまらない場合: 設定ファイルの場所はクライアントごとに異なるため、各ドキュメントを確認してください。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · コンフィグジェネレーター

[Errno 2] No such file or directory / the MCP client times out on a cold start

原因: MCP サーバーがクライアントのファイルシステムを見られないか、モデル読み込み中で初回変換が遅いためです。

簡単な対処: 共有ディレクトリを使うか、docling-serve 経由でリモートモードに切り替えます。

推奨される対処: DOCLING_MCP_CONVERSION_MODE=remote と DOCLING_MCP_SERVICE_URL を設定するか、両プロセスが読める共有フォルダーをマウントします。コールドスタートのタイムアウト回避のためモデルキャッシュを温めます。

当てはまらない場合: Web クライアントはローカル MCP サーバーとファイルシステムを共有しません。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · Docker でのインストール

Token indices sequence length is longer than the specified maximum sequence length for this model (531 > 512)

原因: Transformers が、大きすぎるシーケンスのトークンを数える際に警告し、その後分割します。これは誤報です。

簡単な対処: 警告は無視してかまいません。

推奨される対処: 各チャンクをシリアライズし、同じトークナイザーでトークン数を数えて実際のサイズを確認します。

for c in chunker.chunk(doc):
    print(len(tokenizer.tokenize(chunker.serialize(chunk=c))))

当てはまらない場合: 実際のチャンクがモデル上限を超える場合は、チャンカーと埋め込みモデルのトークナイザーを揃えます。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · RAG ガイド

ImportError: semchunk ... / the chunking extra is required

原因: トークン対応のチャンキング依存関係は docling-core のオプション extra です。

簡単な対処: chunking extra をインストールします。

推奨される対処: Hugging Face トークナイザーには pip install 'docling-core[chunking]'、tiktoken には 'docling-core[chunking-openai]'。

当てはまらない場合: 埋め込みモデルのトークナイザーに合う extra を選びます。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · RAG ガイド

Audio or video conversion fails / the ASR pipeline is not available

原因: ASR はオプション extra で、基本インストールには含まれません。

簡単な対処: asr extra をインストールします。

推奨される対処: pip install "docling[asr]" (または uv add "docling[asr]")。

当てはまらない場合: ASR パイプラインは音声を文字起こしします。動画にはさらに動画パイプラインが必要です。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 対応フォーマット

[WinError 2] The system cannot find the file specified / FileNotFoundError: ffmpeg

原因: Whisper は ffmpeg バイナリを呼び出して音声をデコードするため、インストールされ PATH にある必要があります。

簡単な対処: ffmpeg をインストールし PATH にあることを確認します。

推奨される対処: brew install ffmpeg (macOS)、apt-get install ffmpeg (Debian)、winget install ffmpeg (Windows)。ffmpeg -version で確認します。

当てはまらない場合: すべての音声形式とすべての動画入力で ffmpeg が必要です。

検証済み: Docling v2.129.0 · 最終確認 2026-09-22

公式ソース · 対応フォーマット