Claude Code PDFエラー一覧 — 添付時に出る3つの原因と対処

Claude CodeにPDFを渡すと、PDF too large・PDF is password protected・The PDF file was not validのいずれかで止まることがあります。どれもファイルの状態で決まるエラーで、Claude Codeの設定やネットワークをいじっても直りません。さらにページ範囲を指定して読ませる場面では、pdftoppm is not installedという別の失敗も起きます。

この記事は、出たメッセージから原因を引き、手元のコマンドでファイルのどこが悪いのかを切り分ける流れで進めます。メッセージの文言は公式のエラー一覧に載っているもので、コマンドの出力は筆者の環境(poppler 26.08.0、Ghostscript 9.20で作ったテスト用PDF)で実際に流した結果です。パスワード付きのテスト用PDFは、Ghostscriptの-sUserPasswordと-sOwnerPasswordで作りました。

出たメッセージから原因を引く

3つの添付エラーは、公式のエラー一覧で同じ節にまとまっています。対話セッションでは「Escを2回押してやり直す」よう促す形で表示され、非対話の形では次の文言がそのまま出ます。4つ目のpdftoppm is not installedは、ページ範囲を読ませたときに出る別のメッセージです。

同じ「PDFが読めない」でも、Claude Codeはファイルパスや@メンションで手元のPDFを渡す方式です。ブラウザからアップロードするclaude.aiのチャット添付とは仕組みも上限も別で、そちらはClaudeのPDF読み込み・画像解析の使い方とアップロード上限で扱っています。PDFを読むのではなく新規に作りたい場合も別の話で、Markdownを縦書き日本語PDFに変換する手順のようにLaTeXを介した出力が要ります。

「PDF too large」— 上限を超えたときの回避策

PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).

メッセージにある上限は100ページと20MBです。一方、Readツールが1回に読めるページ数はこれとは別の数字で、次のように決まっています。

公式が挙げる対処は2つです。1つはPDFを丸ごと添付せず、ページ範囲をReadツールで読ませること。もう1つはpdftotextでテキストを抜き、出力ファイルのパスで指すことです。

範囲指定は「このPDFの1〜20ページを読んで」のように依頼文に書くだけで、ファイルを分割する必要はありません。ただし範囲読みはページを画像にして取り込むため、次の節のpopplerが前提になります。図表を読ませる必要がなく文章が中心なら、pdftotextによるテキスト抽出でも足ります。こちらはpdftoppmを使わないので、ページ範囲読みが止まる環境でも試せます。

pdftotext large-report.pdf large-report.txt

pdftotextはページ範囲も切り出せます。12ページのテスト用PDFで-f 1 -l 3を付けると、指定した3ページ分だけが出力されました。

pdftotext -f 1 -l 3 ok.pdf -

page 1
 
page 2
 
page 3

「pdftoppm is not installed」— 範囲読みだけが失敗するとき

pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.

10ページを超えるPDFをページ範囲で読むとき、Claude Codeは各ページをpdftoppmで画像にしてから取り込みます。10ページ以下のPDFは全ページをそのまま読むため、このエラーは大きめのPDFを扱い始めて初めて出やすい失敗です。「小さいPDFは読めたのに、長いPDFだけ止まる」という症状ならここが疑わしくなります。

なお@メンションで渡した10ページ超のPDFは、中身ではなく軽量な参照だけが返る仕様です。@メンションしたPDFでpdfinfoがページ数を数えられないときは、ファイルサイズから推測した数ではなくpage count unknownと表示されます。

入れ方はOSで分かれます。macOSはbrew install poppler、DebianとUbuntuはapt-get install poppler-utilsです。WindowsなどではPATHにpdftoppmが通るpopplerのビルドを用意します。

筆者のMacでは、Homebrewのpoppler1つでpdftoppm・pdftotext・pdfinfoがすべて/opt/homebrew/binに入っていました。範囲読みのために入れたpopplerが、この記事で使う切り分けコマンドもまとめて用意してくれます。

pdftoppm -f 2 -l 3 -png ok.pdf pg
ls pg*

pg-02.png
pg-03.png

上のように、指定した範囲のページだけが連番のPNGになります。Claude Codeの範囲読みがこのコマンドと同じ動きかどうかは確かめていません。ただ、pdftoppmがPATHで見つかるかどうかは手元でwhich pdftoppmを打てば分かります。

「PDF is password protected」— 保護を外してから渡す

PDF is password protected. Try using a CLI tool to extract or convert the PDF.

暗号化されたPDFは、公式の対処に従うならパスワードを外すか、発行元のアプリケーションで保護なしに書き出し直します。APIのPDF対応の要件にも「パスワードや暗号化のない標準的なPDF」とあり、暗号化されたPDFを前提にした経路は見当たりません。

パスワードを外すコマンドの例がqpdfです。なお筆者の環境にはqpdfもpdftkも入っておらず、次のコマンドは実行を確認していません。

qpdf --password=<パスワード> --decrypt protected.pdf unlocked.pdf

保護されているかどうかは、Claude Codeに渡す前にpopplerでも見分けられます。ユーザーパスワード付きで書き出したテスト用PDFにpdfinfoとpdftotextをかけると、どちらも同じ理由で失敗しました。

pdfinfo locked.pdf
pdftotext locked.pdf out.txt

Command Line Error: Incorrect password

pdftotextの終了コードは1でした。保護なしのPDFではpdfinfoがPages: 12のようにページ数を返すので、このメッセージの有無が保護の目安になります。権限だけを制限した暗号化PDFはpopplerで開けてPagesも返ります(Ghostscript 9.20でオーナーパスワードだけを付けたテスト用PDFで確認しました)。その場合はpdfinfoが出すEncrypted: yes (print:no copy:no change:no ...)の行で見分けます。APIの要件からは外れるためです。Claude Codeがそうした暗号化PDFをどう扱うかは、公式に記述が見当たりません。ここはAPIの要件からの推論です。社内の文書管理システムから書き出したPDFなら、CLIで外すより書き出し設定を変えるほうが手間は少なく済みます。NotePM・DocuWorks・SharePointのMCP対応は文書管理システムMCP対応 — NotePM・DocuWorks・SharePointの3経路で比べています。

「The PDF file was not valid」— 壊れているのか別形式なのか

The PDF file was not valid. Try converting it to text first (e.g., pdftotext).

このメッセージはPDFとして解釈できなかったことしか教えてくれません。原因は、ダウンロードが途中で切れた破損ファイル、拡張子だけ.pdfにした別形式のファイル、仕様に沿わない書き出しの3つに分かれ、直し方がそれぞれ違います。

手元で3種類のファイルを作って、同じコマンドをかけてみました。用意したのは、途中で切った1,500バイトのPDF(trunc.pdf)、文字列helloを.pdf名で保存したファイル(fake.pdf)、PNG画像の拡張子を.pdfにしたファイル(img.pdf)です。

file ok.pdf trunc.pdf fake.pdf img.pdf

ok.pdf:    PDF document, version 1.4, 12 pages
trunc.pdf: PDF document, version 1.4, 12 pages
fake.pdf:  ASCII text, with no line terminators
img.pdf:   PNG image data, 1 x 1, 8-bit/color RGB, non-interlaced

fileが実体を言い当てるのは別形式のケースです。途中で切れたPDFは、先頭のヘッダーが残るので正常なPDFと同じ表示になることがあります。破損の見分けには使えません。

破損を見分けるのはpdfinfoです。3つとも失敗し、違いはエラー文の先頭に出ます。次は末尾の2行の抜粋です。

pdfinfo trunc.pdf

Syntax Error: Couldn't find trailer dictionary
Syntax Error: Couldn't read xref table

fake.pdfとimg.pdfはMay not be a PDF fileという警告が最初に付き、そのあと同じCouldn't read xref tableで終わります。Claude Codeの判定と一致する保証はありませんが、popplerでも読めないなら、破損か別形式を疑う手がかりになります。直し方は、破損なら元のファイルを取り直し、別形式なら元の形式のまま渡し、書き出しが原因なら発行元で再エクスポートすることです。

複数のPDFのどれが原因かを特定する

3つのエラー文言のどれにもファイル名は含まれません。複数のPDFを一度に渡すと、どれが原因か分からなくなります。そこで、渡す前に次の順で確かめると原因が絞れます。

ディレクトリ内の全PDFにpdfinfoを順にかけ、ページ数か失敗理由を1行にまとめるループが便利です。手元の6ファイル(権限だけを制限したrestricted.pdfを含む)では次のように出ました。

for f in *.pdf; do printf '%s: ' "$f"; pdfinfo "$f" 2>&1 | grep -E "^Pages|^Encrypted:[[:space:]]+yes|Incorrect password|Couldn't read xref" | sed 's/  */ /g' | paste -sd' ' -; done

fake.pdf: Syntax Error: Couldn't read xref table
img.pdf: Syntax Error: Couldn't read xref table
locked.pdf: Command Line Error: Incorrect password
ok.pdf: Pages: 12
restricted.pdf: Pages: 12 Encrypted: yes (print:no copy:no change:no addNotes:no algorithm:RC4)
trunc.pdf: Syntax Error: Couldn't read xref table

行にPagesだけが出たファイルは暗号化なしです。Encrypted: yesが並んだrestricted.pdfは、パスワードなしで開けてもページ数が取れてしまうので、Encrypted:の行を拾わないと見落とします。末尾にhead -1を付けると、Pagesの行が先に出るためEncrypted:が切り捨てられるので付けません。ここでも、popplerで読めてもClaude Codeが受け付ける保証はありません。あとは、ページ数とサイズを見て上限を超えるものを分ける作業です。

サイズを同時に見たいときは、pdfinfo contract.pdf | grep -E "Pages|File size"のように絞れば1行ずつ確認できます。ベンダー契約書のように150ページを超える資料は、渡す前に分かれば1回の依頼で済みます。よく使う手順ならCLAUDE.mdに「PDFは最初にpdfinfoでページ数とサイズを確認し、100ページ超はpdftotextで抽出する」と書いておくと、毎回の指示が省けます。

API側のPDF上限はClaude Codeとは別物

Claude Codeの100ページ・20MBという数字は、添付時のtoo largeのメッセージに出るものです。AnthropicのAPIにPDFを渡す場合は、別の上限が決まっています。

APIではページが画像としても処理されるため、文字が細かいページや表の多いPDFはページ数の上限より先にコンテキストウィンドウを使い切ることがあります。大きなPDFでもFiles APIに載せてfile_idで参照すればリクエストは小さくなりますが、上限に達する前に失敗する場合がある点は公式が注意しています。実装の詳細はClaude Files APIでPDFを処理する方法にまとめています。

まとめ

エラー文言にファイル名は出ないので、複数のPDFを渡す前にpdfinfoのループで1本ずつ確かめるのが早道です。popplerで開けても暗号化が残っていれば、書き出し直しを先に検討します。長いPDFだけが止まるなら、popplerの有無を疑います。