エラーを貼り付ける#
エラーメッセージかトレースバックの最後の数行を貼り付けてください。照合はブラウザ内で行われ、どこにも送信されません。カテゴリ別にすべての項目を読むこともできます。エラー文はターミナルの表示と同じ英語の原文のままです。
どんな Docling の不具合も 4 ステップで調べる#
- バージョンと Python を確認
docling --version python --version「不明なオプション」「機能がない」という報告の多くは古い Docling が原因で、Python 3.9 によることがよくあります。
- 本当のエラーを得る
docling convert problem.pdf -vv 2>&1 | tail -40 - ステージを切り分ける
--no-ocr、次に--no-tablesを付けて再実行します。エラーが消えれば、そのステージ（多くは OCR エンジンかその言語）に問題があります。 - Docling が見たものを確認
docling convert problem.pdf --to html_split_page --show-layout各ページと抽出結果が横に並び、レイアウトの枠が描かれます。表の誤り、文字の欠落、読み順の誤りを診断する最速の方法です。
エラーは出ないが出力がおかしい#
| 症状 | 考えられる原因 | 試すこと |
|---|---|---|
| スキャン PDF の出力が空か文字化け | PDF に誤ったテキスト層があり、OCR が飛ばされた | --ocr-mode full_page |
| ビューアでは正しく見えるのに、抽出すると文字化け（“8VceZWZTReV”） | フォントがグリフを誤った文字に対応付けている | --replace-broken-text-layer（2.144.0 以降）で該当ページだけ OCR。OCR ガイド参照 |
見出しがすべて ## になる | レイアウトモデルは見出しを判定するがレベルは判定しない | --heading-hierarchy（2.144.0 以降） |
| 横向きのスキャンページを RapidOCR が読めない | RapidOCR の行分類は 180° の反転しか扱わない | --ocr-option detect_orientation=true（2.145.0 以降） |
| 日本語のスキャンで文字を誤認識 | OCR モデルの既定の言語 | エンジンのコードか iso:ja を --ocr-lang に指定——OCR ガイド参照 |
| 表の 2 行が 1 つのセルに結合 | 横罫線のない表（Docling レポート自身の表 1 で再現） | --show-layout で確認し、そのページで VLM パイプラインを試す |
| 単語がくっつく（“MaksymLysak”） | PDF のテキスト層の字間が詰まっている | --pdf-backend pypdfium2 と比較、または --ocr-mode full_page |
| Markdown ファイルが巨大 | base64 で埋め込まれた画像（CLI の既定は embedded） | --image-export-mode placeholder または referenced |
| 本文にヘッダー・フッターが混ざる | ページの付属要素を含む文書全体を読んでいる | 本文だけを書き出す（既定の Markdown 出力はページのヘッダー・フッターを省きます） |
| チャンクが表の途中で切れる、埋め込みには長すぎる | HierarchicalChunker か合わないトークナイザー | 埋め込みモデルのトークナイザーで HybridChunker——RAG とチャンク参照 |
それでも解決しない場合#
エラー文そのままで公式の issue トラッカーを検索してください。新しい issue を立てるときは docling --version の出力、OS、最小限の再現ファイルを添えます。このページの内容が誤っている、または解決策が効かなくなった場合は hello@docling.org までメールしてください。
よくある質問
Docling が onnxruntime is not installed と言うのはなぜ？
--ocr-engine rapidocr は RapidOCR の onnxruntime バックエンドを使いますが、既定の pip install docling には含まれないためです。docling[rapidocr] をインストールするか、--ocr-option backend=torch で既に入っている PyTorch バックエンドを使ってください。
インストール後に Docling の新しいオプションがないのはなぜ？
docling --version を確認してください。Python 3.9 では pip が 3.9 対応の最後のバージョンである Docling 2.69.1 をエラーなしでインストールします。最新版には Python 3.10–3.14 を使ってください。
Docling で文書が失敗した理由を見るには？
同じファイルを -vv 付きで実行してデバッグログを出します。CLI の “Document … failed to convert” は要約で、実際の例外はその上に記録されています。
Docling が .doc・.ppt・.xls で失敗するのはなぜ？
これらの旧形式（と .rtf）は、まず LibreOffice で .docx・.pptx・.xlsx に変換されます。LibreOffice をインストールして soffice を PATH に通すか、DOCLING_LIBREOFFICE_CMD を設定してください。
出典
- Docling 2.148.0 ソースコード（エラーメッセージ）
- Docling の GitHub issues
- Granite-Docling モデルカード：トラブルシューティング
- docling-serve 1.38.2 ソース