exceeds maximum allowed tokensエラーの原因と対処法 — Claude Code

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ツール由来のケースの見分け方をまとめます。

「File content ... exceeds maximum allowed tokens」とは何のエラーか

このエラーは、GitHub issue #4002で2025年7月に報告されたもので、Sonnetを使っていた投稿者が特別大きくもないコードベースを読ませただけで発生したと説明しています。エラー文の28375 tokensと25000という数字は、ファイルの実際のトークン数とReadツールの上限を示しており、投稿者が引き合いに出した「Sonnetは64,000、Opusは32,000まで出力できるのに」というモデルの出力上限とも、200Kのコンテキストウィンドウとも別の、Readツール固有の値です。

コメント欄では「200Kのコンテキストがあるのに、小さいコードベースなのになぜすぐ埋まるのか」という混同も見られますが、これは「Context exceeds token limit」の意味と対処で扱っている会話全体の上限とは別のレイヤーです。あちらは会話の蓄積がモデルの上限に近づいたときの警告で、/compactや/clearで対処します。今回のエラーは、1回のファイル読み込みという単発の呼び出しに対する上限で、会話がどれだけ空いていても、読もうとしたファイル自体が大きければ発生します。

当時のユーザーの中には、node_modules配下のcli.jsを直接書き換えて25000という数値をsedで置換し、上限を引き上げていた例もありました。インストール済みパッケージの内部実装を直接改変する方法で、アップデートのたびに元に戻る上に公式にサポートされた手段ではありません。同じ「上限を上げたい」という目的は、v2.1.145より前のv2.1.0(2026年1月7日)で追加されたCLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS環境変数を使えば、公式にサポートされた形で果たせます。

issue #4002は2025年7月20日に立てられ、最後のコメントは同年9月10日についています。この間、コメント欄では原因の異なる複数の症状が同じ言い回しで報告され続けました。投稿者と同じように単純なファイル読み込みで発生した報告のほか、MCPツール全般の出力が絡む報告もあります。文言が同じ「exceeds maximum allowed tokens」で揃っているため、issueを読むだけではReadツール由来かMCPツール由来かを切り分けにくい状態でした。

v2.1.145で何が変わったか — エラーから自動ページングへ

このエラー文言そのものは、Claude Codeのバージョンによって出方が変わります。changelogには次の記載があります。

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

v2.1.145(2026年5月19日)のこの変更で、Readツールは「上限を超えたら即エラー」から「超えた分は自動的に最初のページだけ返し、続きの読み方を案内する」という動きに変わりました。

offsetやlimitを明示指定した読み込みが上限を超えた場合は、v2.1.145の前後を問わずエラーになります。この中で、選択範囲に極端に長い1行を含むケースだけはさらにもう1段階の変化がありました。v2.1.208より前は、明示的なlimit付きの読み込みでも一度は選択範囲の全体をメモリに読み込んでから上限超過を判定していたため、1行が極端に長いとメモリ不足を起こす危険がありました。v2.1.208以降は、選択した行が上限を超えると分かった時点で読み込み自体を打ち切ってエラーを返すため、メモリ上に無駄に長い1行を抱え込みません。

公式ドキュメントの現在の説明では、Readツールは既定でファイルの先頭から返し、ファイル全体の読み込みが上限を超える場合は先頭ページとPARTIAL view通知を返して、offsetとlimitを使ったさらなる読み込み方法をClaudeに伝えます。この通知はユーザーではなくClaude自身に向けたものなので、範囲指定なしの読み込みで引っかかった場合は、Claudeが通知を読んで続きをoffset/limit付きで自分から読み直すのが通常の流れです。ユーザー側で毎回手動の指示を挟む必要はありません。一方で、offsetやlimitを明示的に指定した読み込みがそれでも上限を超える場合は、いまもエラーになります。つまりv2.1.145の改善が効くのは「範囲指定なしでファイル全体を読もうとした」ケースに限られ、範囲を絞った読み込みで超過した場合の挙動は変わっていません。

今この文言のエラーに出会う条件

v2.1.145以降の環境で、GitHub issueと同じ文言のエラーに出会うのは主に次のケースです。

• 明示的なoffset/limit付きの読み込みがそれ自体で上限を超える: 例えば1万行のうち5,000行分を指定したら、その5,000行だけでも上限を超えていた場合です
• 選択範囲に極端に長い1行が含まれる: minifyされたJSや、改行のない巨大なJSON・ログ行のように、1行だけで上限に達するケースでは、ページ送りでは対応できずエラーになります。公式ドキュメントは、この場合はlimitを小さくするか、Grepで特定の内容を検索する方法に切り替えるよう案内しています
• v2.1.145より前のバージョンを使っている: この場合は範囲指定なしの通常のファイル読み込みでも、以前と同じ「即エラー」の挙動になります

いずれのケースも、大きなファイルを分割せず全体で読み切りたい事情がある場合はCLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS環境変数でReadツールの上限そのものを引き上げる選択肢があります。特に2つ目のケースでは、GrepToolによる検索がそのまま有効な回避策です。ファイル全体を読み込む代わりに、探している内容だけをパターンで絞り込みます。

grep -n "search-term" path/to/large-file.log

Claude Codeに対しては、「このファイルは大きいので、まずgrepで該当箇所を探してから必要な範囲だけ読んで」のように指示すると、同じ考え方をエージェントに伝えられます。

バージョンが古いために発生している場合は、まずアップデートで解消するかを確認します。

claude --version

MCPツールの出力で同じ数字が出るケース(原因は別)

GitHub issueのコメント欄では、Playwright MCPのbrowser_wait_forが返す応答について「MCP tool "browser_wait_for" response (45599 tokens) exceeds maximum allowed tokens (25000)」という、酷似した文言のエラーが報告されています。これはReadツールのファイル読み込み上限ではなく、MCPツールの応答に別途かかっている上限です。issue当時のエラー文ではどちらも25000という同じ数字が表示されていたため、文言だけを見ると同じ問題に見えてしまいます。issue報告があった2025年当時はMCP側もこのようにエラーで止まっていましたが、現在は挙動が変わり、超過分はエラーではなくファイル保存に切り替わります。

MCPツールの出力上限は現在、超過した結果を会話にそのまま流し込む代わりにファイルへ保存し、参照だけを会話に渡す仕組みになっており、エラーで止まる挙動ではありません。この上限の既定値・警告しきい値・サーバー側で個別に上限を引き上げるanthropic/maxResultSizeCharsアノテーションとの使い分けは、MAX_MCP_OUTPUT_TOKENSとはにまとめています。手元のエラーがファイル読み込みなのかMCPツールの応答なのかを見分けるには、エラーメッセージの主語(File contentか、MCPツール名やMCP toolの記載か)を確認してください。名前が紛らわしいCLAUDE_CODE_MAX_OUTPUT_TOKENSという環境変数もありますが、これはモデル自体の出力トークン数を制御するもので、Readツールのファイル読み込み上限やMCPツールの応答上限とは別の仕組みです。

似た「◯◯ exceeds」系のエラーとしては、thinkingの予算設定に関する「Thinking budget exceeds」エラーの原因と対処法もあります。いずれも文言は似ていますが、上限がかかっている対象がそれぞれ異なる点は共通しています。

まとめ

「File content ... exceeds maximum allowed tokens」は、会話全体のコンテキストウィンドウではなく、Readツールが1回のファイル読み込みで扱える量に対する上限です。v2.1.145より前は範囲指定なしの読み込みでもすぐエラーになっていましたが、それ以降は自動的に先頭ページを返して続きの読み方を案内する動きに変わりました。今でもエラーになるのは、offset/limitを指定した範囲自体が大きすぎる場合や、極端に長い1行を含む場合です。上限そのものを引き上げたい場合はCLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS環境変数が使えます。文言が似ているMCPツールの出力上限とは原因も対処も別物なので、エラーの主語を確認してから対処法を選んでください。