exceeds maximum allowed tokensエラーの原因と対処法 — Claude Code
Claude Codeの「File content exceeds maximum allowed tokens」エラーの原因と、v2.1.145で変わった自動ページング、MCPツールの同名エラーとの違いを解説します。
Claude Codeで大きめのファイルを読み込ませたとき、「File content (28375 tokens) exceeds maximum allowed tokens (25000). Please use offset and limit parameters to read specific portions of the file, or use the GrepTool to search for specific content.」というエラーで処理が止まることがあります。原因はReadツールが1回の呼び出しで返せる内容量にかかる上限です。v2.1.145でこの挙動は大きく変わり、範囲指定なしの読み込みならエラーで止まらず、自動でページ送りして続行するのが基本の動きになりました。それでも同じ文言に出会う条件と、原因がMCPツール側にあるケースの見分け方を順に見ていきます。
まず切り分ける — エラー文の主語と呼び出し方
同じ「exceeds maximum allowed tokens」でも、原因はファイル読み込みとMCPツールの応答で別々です。手元で出たエラーは、次の順に当てはめると対処が決まります。
エラーが出たときの切り分け
- 1
エラー文の頭を見る
「File content」で始まればReadツール、
MCP tool "…"で始まればMCPツールの応答です。後者はMAX_MCP_OUTPUT_TOKENSの解説の領域になります。 - 2
Claude Codeのバージョンを見る
v2.1.145より前なら、範囲指定なしの読み込みでも即エラーになります。アップデートで挙動が変わります。
- 3
範囲指定の有無を見る
offsetやlimitを付けた読み込みが超過したときは、v2.1.145以降でもエラーのままです。範囲を狭めて読み直させます。 - 4
1行が極端に長くないか見る
limit付きの読み込みで1行が上限を超えるときは、limitを小さくするか、Grepで必要な箇所だけ探させます。 - 5
それでも全体を読ませたいとき
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENSでReadツールの上限そのものを上書きします。
バージョンは次のコマンドで確かめます。v2.1.289で実行した出力は下のとおりです。
claude --version2.1.289 (Claude Code)なぜReadツールに上限があるのか — issue #4002の経緯
このエラーは、GitHub issue #4002で2025年7月20日に報告されました。Sonnetを使う投稿者は、いくつかのファイルを読ませたところで発生したと書いています。エラー文の28375 tokensはファイルの実際のトークン数、25000はReadツールの上限です。投稿者が引き合いに出した「Sonnetは64,000、Opusは32,000まで出力できる」というモデルの出力上限とも、200Kのコンテキストウィンドウとも別の、Read固有の値です。
issueは12月2日に完了扱いで閉じられ、12月10日に自動でロックされました。閉じる前の12月2日のコメントで、Anthropicの担当者が上限を置いた理由を説明しています。極端に長いファイルを一度に読むとコンテキストウィンドウが埋まり、compactionが走って利用者が困っていたため、というのが理由です。あわせて、複数回の読み込みに分ければファイル全体を読めることも述べています。
issueでは足かせとして受け止められましたが、設計の狙いはコンテキストの保護にあります。上限を引き上げるなら、そのぶん会話の余白を食うことになります。
Readツールの上限まわりの変遷
- 2025年7月20日issue #4002が立つ
「File content ... exceeds maximum allowed tokens」を報告。同じ文言でMCPツールの報告も集まりました。
- 2026年1月7日v2.1.0で環境変数が追加
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENSで、ファイル読み込みの上限を上書きできるようになりました。 - 2026年5月19日v2.1.145で自動ページングに
全体読み込みが上限を超えると、エラーでなく先頭ページと
PARTIAL view通知を返す動きになりました。 - 2026年7月14日v2.1.208で長い1行の扱いを改善
limit付きの読み込みで1行が極端に長いとき、全体をメモリに載せずエラーを返します。
コメント欄で試された回避策と取り違え
issueのコメント欄には、公式の手段が整う前に試された方法がいくつか残っています。
- インストール済みの
cli.jsをsedで書き換える: 2025年9月10日に「25000を100000に置換した」という報告がありました。インストール先のファイルを直接書き換える方法なので、公式の手段ではありません。上限の引き上げという目的は、v2.1.0で追加された環境変数が公式の手段として担います CLAUDE_CODE_MAX_OUTPUT_TOKENSを設定する: 9月29日のコメントがWindowsの環境変数画面で設定を勧めています。この変数が制御するのはモデルの出力トークン数で、Readツールのファイル読み込み上限とは別物ですMAX_MCP_OUTPUT_TOKENSを設定する: 8月5日のコメントが勧め、8月24日に「MCPツールには効くが、ファイルとコンテキスト用が要る」という返信がつきました。この変数もMCPツールの応答にかかるもので、ファイル読み込みには効きません
読み込みで引っかかったファイルには、Skill内から参照するテキストもありました。11月27日のコメントは、MicrosoftのRustガイドライン(25,630トークン)をSkillから読ませようとして、上限をわずかに超えた例です。分量が上限ぎりぎりのファイルほど、この種の失敗が出やすくなります。
会話全体の上限と取り違えるコメントもありました。issue本文には、「200Kのコンテキストがあるのに、小さいコードベースでなぜすぐ埋まるのか」という疑問も書かれています。
会話の蓄積がモデルの上限に近づく警告は、「Context exceeds token limit」の意味と対処で扱っています。そちらは/compactや/clearで対処します。今回のエラーは1回のファイル読み込みという単発の呼び出しにかかる上限で、会話がどれだけ空いていても、読もうとしたファイル自体が大きければ発生します。
v2.1.145で何が変わったか — エラーから自動ページングへ
Claude Codeのchangelogには、v2.1.145の変更として次の記載があります。
Improved the Read tool to return a truncated first page with a "PARTIAL view" notice instead of a hard error when a whole-file read exceeds the token limit
Readツールは「上限を超えたら即エラー」から「超えた分は先頭ページだけ返し、続きの読み方を案内する」動きに変わりました。
| 挙動 | v2.1.144以前 | v2.1.145以降 |
|---|---|---|
| 範囲指定なしで全体を読み、上限超過 | v2.1.144以前エラーで停止 | v2.1.145以降先頭ページ + PARTIAL view通知で継続 |
offset/limitを明示指定して、それでも超過 | v2.1.144以前エラー | v2.1.145以降変わらずエラー |
PARTIAL viewの通知は、ユーザーでなくClaude自身に向けたものです。受け取った量と、offset・limitで続きを読む方法が書かれています。
この通知には、編集との関係でもう1つ効いてくる点があります。Claudeはファイルを編集する前に、同じ会話の中でそのファイルを読んでいる必要があります。PARTIAL view通知つきで途中まで読んだだけの状態は、この「読んだ」に数えられません。Claude Opus 4.6やHaiku 4.5などの旧モデルは常に事前の読み込みが必要で、Jupyter notebookは、上書き(Write)でも全モデルで事前の読み込みが必要です。大きなファイルの末尾付近を編集させたいときは、該当範囲をoffsetとlimitで読ませてから編集に進みます。
今この文言のエラーに出会う条件
v2.1.145以降の環境で、issueと同じ文言のエラーに出会うのは主に次のケースです。
- 明示的な
offset/limit付きの読み込みが、それ自体で上限を超える: 1万行のうち5,000行を指定して、その5,000行だけで上限を超えた場合です - 選択範囲に極端に長い1行が含まれる: 選択範囲が上限を超えるとエラーになります。エラー文は、
limitを小さくするか、Grepで特定の内容を検索するよう促します - v2.1.145より前のバージョンを使っている: 範囲指定なしの通常の読み込みでも、以前と同じ「即エラー」の挙動になります
2つ目のケースについて、v2.1.208より前は、選択範囲を一度メモリに読み込んでから判定していたので、極端に長い1行があるとメモリ不足の危険がありました。
Grepで必要な箇所だけ読む
長い1行を含むファイルでは、全体を読む代わりに、探している内容をパターンで絞ります。
grep -n "search-term" path/to/large-file.logClaude Codeには「このファイルは大きいので、まずgrepで該当箇所を探してから、必要な範囲だけ読んで」と指示すれば、同じ進め方を任せられます。
上限そのものを引き上げる
全体を分割せずに読み切りたい事情があるときは、環境変数で上限を上書きします。変数の説明は公式ドキュメントで「ファイル読み込みの既定のトークン上限を上書きする。大きなファイルを全体で読む必要があるときに使う」とされています。
export CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=50000
claude50000は例です。大きくするほど、1回の読み込みでコンテキストを使う量も増えます。前節の担当者コメントが挙げた理由のとおり、compactionが早く走る要因になるので、必要なファイルだけに限った場面で使います。
MCPツールの出力で同じ数字が出るケース(原因は別)
issueのコメント欄には、Playwright MCPのbrowser_wait_forが返した応答について、「MCP tool "browser_wait_for" response (45599 tokens) exceeds maximum allowed tokens (25000)」という酷似した文言のエラーが報告されています。
これはファイル読み込みの上限ではなく、MCPツールの応答に別途かかっている上限です。当時はどちらも25000と表示されたため、文言だけでは同じ問題に見えました。担当者は12月2日のコメントで、MCPの問題は別のissueで扱いたいと述べています。
| 発生源 | 対象 | 既定の上限 | 主な対処 |
|---|---|---|---|
| Readツール | 対象ファイル1回分の読み込み | 既定の上限数値は公式ドキュメントに記載なし(issue当時のエラー文では25000) | 主な対処offset/limit調整、Grep、CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS |
| MCPツールの応答 | 対象MCPサーバーが返す1回の結果 | 既定の上限25,000トークン | 主な対処MAX_MCP_OUTPUT_TOKENSで変更 |
MCP側は現在、画像を含まない結果が上限を超えると、会話にそのまま流す代わりにファイルへ保存し、ファイルパスだけを会話に渡します。エラーで止まる挙動ではありません。保存先はセッションのtool-resultsディレクトリです。
上限の既定値と警告のしきい値(10,000トークン)、サーバー側で個別に引き上げるanthropic/maxResultSizeCharsとの使い分けは、MAX_MCP_OUTPUT_TOKENSとはにまとめています。
名前が紛らわしいCLAUDE_CODE_MAX_OUTPUT_TOKENSは、モデルの出力トークン数を決める変数です。ファイル読み込みの上限にも、MCPの応答上限にも効きません。
似た「◯◯ exceeds」系のエラーとしては、thinkingの予算設定に関する「Thinking budget exceeds」エラーの原因と対処法もあります。
まとめ
エラー文が「File content」で始まるなら、範囲指定なしの読み込みはv2.1.145以降で自動ページングに任せられ、手を入れるのは範囲指定が大きすぎる場合と長い1行の場合です。MCPツール名で始まる場合は別の上限なので、MAX_MCP_OUTPUT_TOKENS側で調整します。上限の引き上げは1回の読み込みで使うコンテキストと引き換えなので、必要なファイルに限る使い方になります。