Claude Code settings 2MiBエラーの直し方 — settings.json肥大化の対処
claude --settingsに渡したファイルが2MiBを超えると起動時に終了します。境界のバイト数、別エラーとの見分け方、.mcp.jsonの同型エラーを実機の出力で示します。
このTipsでできること
claude --settingsに渡したファイルが2MiBを超えていると、Claude CodeはError: Settings file exceeds the 2MiB limitを出して終了コード1で止まります。~/.claude/settings.jsonや.claude/settings.jsonが肥大化したのではなく、--settingsの引数が別の大きなファイルを指している場合が対象です。
この記事では、エラーの出方をバイト数の境界まで実機で確かめた結果と、似て見える別のエラーとの見分け方、.mcp.jsonに出る同型のエラーを扱います。実機での再現はClaude Code v2.1.289です。HOMEとCLAUDE_CONFIG_DIRを空のディレクトリにすれば、同じ手順で安全に再現できます。
エラーが出たときの切り分け
まず、画面に出たメッセージの種類で原因が分かれます。
| 画面のメッセージ | 原因 | 直し方 |
|---|---|---|
Settings file exceeds the 2MiB limit: <絶対パス> | 原因渡したファイルが2MiB(2,097,152バイト)より大きい | 直し方末尾のパスが意図したファイルか確認する |
Cannot use settings file (EISDIR: …) | 原因ファイルでなくディレクトリを渡した | 直し方JSONファイルのパスに直す |
Cannot use settings file (Not a regular file (device, FIFO, or socket)) | 原因/dev/zeroやFIFOなど通常のファイルでないものを渡した | 直し方通常のJSONファイルを渡す |
Settings file not found: <パス> | 原因パスが存在しない | 直し方パスの綴りと作業ディレクトリを見直す |
どの行にも、読み込もうとしたファイルのパスが付きます。最初の一手は、このパスが意図した設定ファイルと一致しているかを見ることです。
実機で確かめたエラーの出方
2.2MB(2,200,003バイト)の空白入りJSON、ディレクトリ、/dev/zeroをそれぞれ--settingsに渡し、claude doctorを実行しました。doctorは設定の読み込みまでは進むため、モデルを呼ばずにエラーだけを再現できます。実行時はHOMEとCLAUDE_CONFIG_DIRを空の一時ディレクトリに差し替えたので、手元のユーザー設定は読み込まれていません。同じ手順で、自分の環境でも安全に再現できます。
$ claude --settings big.json doctor
Error: Settings file exceeds the 2MiB limit: /private/tmp/w2mib/big.json
$ claude --settings d doctor # d はディレクトリ
Error: Cannot use settings file (EISDIR: illegal operation on a directory, read): /private/tmp/w2mib/d
$ claude --settings /dev/zero doctor
Error: Cannot use settings file (Not a regular file (device, FIFO, or socket)): /dev/zero3つとも終了コードは1でした。/dev/zeroは無限に読み出せるため、v2.1.214より前は読み込みが止まらずメモリを使い続けました。いまは読み込みの前に弾かれ、doctorも走りません。
境界はちょうど2,097,152バイト
2MiBは2,097,152バイトです。中身が{}で残りを空白で埋めた2つのファイルで、境界を測りました。
1バイトで分かれる境界
2,097,152バイト
読み込めてdoctorが動きます(終了コード0)。
2,097,153バイト
exceeds the 2MiB limitで終了コード1になります。
公式のCLIリファレンスは「2MiB以下の通常のファイル」と書いています。自作した大きな設定が境界に近いときは、この1バイトの差で挙動が変わります。
サイズ判定は中身の解釈より前
サイズ判定は中身を解釈する前に行われます。壊れたJSON({ bad)を書いたファイルを渡してもサイズ超過のエラーにはならず、同じdoctorはそのまま起動しました。中身が空のファイルも同様に起動します。存在しないパスは、サイズ判定ではなくSettings file not foundで止まります。
サブコマンドや--versionでも止まる
この判定は、設定を実際に使うセッションの前ではなく、起動の入り口で働きます。2.2MBのファイルを渡したまま、次のコマンドを実行しました。
| 実行したコマンド | 結果 |
|---|---|
claude --settings big.json --version | 結果exceeds the 2MiB limit、終了コード1 |
claude --settings big.json mcp list --help | 結果同上 |
claude --settings big.json auto-mode defaults | 結果同上 |
バージョン表示やヘルプのように設定を使わないコマンドでも、大きなファイルを渡せば止まります。CIスクリプトで--settingsを共通のオプションに入れているときは、どのコマンドで落ちても原因は同じファイルです。
別のファイルを指す経路でも判定は同じ
シンボリックリンクは、リンク先の実体で判定されました。2.2MBのファイルへのリンクはサイズ超過、/dev/zeroへのリンクと、mkfifoで作ったFIFOは、通常のファイルでないものとして弾かれました。
インラインJSONの書き間違いにも注意が要ります。--settings '{bad'のように壊れた文字列を渡すと、JSONの構文エラーにはなりませんでした。Settings file not found: /private/tmp/w2mib/{badと出て、文字列全体がファイルのパスとして扱われた形です。引用符やシェルの展開を疑うときは、メッセージ末尾に出る「パスとして読まれた文字列」を見れば、実際に何が渡ったかが分かります。
起きやすいパス指定ミス
--settingsの上限に当たるのは渡したファイルなので、まず別の大きなファイルを指していないかを疑います。
パス指定ミスの3型
変数の展開違い
--settings "$CONFIG_PATH"で、変数に別のログやビルド成果物のパスが入っている。サイズ超過のエラーになります。ディレクトリの指定
--settings .claudeのようにディレクトリを渡すと、サイズではなくEISDIRで止まります。JSONでない文字列の指定
--settings "$(env)"のようにJSONでない文字列を渡すと、パスとして扱われ、ENAMETOOLONGなどのパスのエラーになります。2MiBのエラーとは別物です。
パスの中身は、実行前に次のコマンドで見られます。
ls -la "$CONFIG_PATH" # サイズと種類(先頭が - なら通常のファイル、d ならディレクトリ)
stat -f %z "$CONFIG_PATH" # バイト数(macOS。Linuxは stat -c %s)--settingsに有効なJSON文字列を渡す場合、2MiBの上限が書かれているのはファイルのみです(CLIリファレンス)。--settings '{"permissions":{"defaultMode":"acceptEdits"}}'のような短い指定で、このエラーに当たることは考えにくいでしょう。
--settingsと4スコープの関係
Claude Codeの設定ファイルは、Managed・User・Project・Localの4スコープに分かれています。
| スコープ | 置き場所 | 対象範囲 |
|---|---|---|
| Managed | 置き場所サーバー配信 / OSのレジストリ・plist / システムのmanaged-settings.json | 対象範囲組織全体、またはマシン上の全ユーザー |
| User | 置き場所~/.claude/settings.json | 対象範囲自分、全プロジェクト共通 |
| Project | 置き場所リポジトリの.claude/settings.json | 対象範囲リポジトリの共同作業者全員(git管理) |
| Local | 置き場所.claude/settings.local.json | 対象範囲自分、このリポジトリのみ(git管理外) |
--settingsはこの4つのどれでもなく、コマンドライン引数による1セッション限りの上書きです。優先順位はManagedが最上位で、次にコマンドライン引数、その下がLocal、Project、Userの順です。--settingsで渡したキーはLocalやProjectより強く効き、渡さなかったキーはファイル側の値が残ります。
ただし、ManagedはCLI引数でも上書きできません。--settingsで渡した値が、Managedで固定された同じキーに勝つことはありません。permissions.allowのようなリストは、スコープ同士で置き換えずに結合されます。個人・チーム・組織のレイヤーで権限をどこまで固定するかは、Claude Codeセキュリティ・権限ガイドで扱っています。
--settingsで何を渡せるか
渡したJSONは、ユーザー設定のファイルに書けるキーならどれでも設定できます。例外はManagedのキーとグローバル設定のキーで、これらは--settingsでは設定できません。制限付きで動かす--restrictedでは、コマンドを実行する組み込みツールを外し、ユーザーとプロジェクトの設定ファイルを読まずに、Managed設定と--settingsだけを読みます。共有マシンで評価用のスクリプトからClaude Codeを動かすときに、設定の入り口を--settingsの1本に絞れる作りです。
claude agentsも--settingsを受け付けます。claude agentsでも、ファイルなら同じ2MiBの判定を通るはずです。
実際にsettings.jsonが膨らんだときの見直し
エラーを出しているのが--settingsではなく、通常の.claude/settings.jsonが大きくなっただけの場合は、別の話です。公式のエラー一覧が2MiBの上限として書いているのは、--settingsに渡したファイルです。
サイズとキーの偏りは、次の2コマンドで見られます。
ls -la .claude/settings.json
jq 'keys' .claude/settings.json膨らみやすいのは、permissions.allowの列挙、hooksにインラインで書いた長いスクリプト、envブロックの大量の変数です。hooksのスクリプトは外部ファイルに切り出し、設定にはパスだけを書くと、ファイルのサイズと読みやすさが両方改善します。許可ルールが多いときは、1件ずつの列挙をディレクトリ単位のルールにまとめられないかを見ます。設定キー全体の整理はClaude Code settings.json完全ガイドが詳しいです。
CIで一時的に上書きする使い方
--settingsが合うのは、そのセッションだけ設定を変えたい場面です。CIで通常より緩い権限モードを一時的に使う、複数の設定を切り替えてテストする、といった使い方です。
claude -p "このPRの差分をレビューして" \
--settings '{"permissions":{"defaultMode":"acceptEdits"}}'ファイルパスで渡す運用の場合は、実行ログにそのパスを出しておくと、同じエラーが出たときに2MiB超のファイルを取り違えたのか、パス自体が間違っているのかを、ログの1行から追えます。起動前にサイズを測る手もあります。次の1行は、2,097,152バイトを超えていれば非0で終わります。
test "$(wc -c < "$CONFIG_PATH")" -le 2097152CIスクリプトでは終了コードが1になるため、起動失敗の判定にもそのまま使えます。
.mcp.jsonにも2MiBの同型エラーがある
同じ2MiBの上限は、--settings以外にもあります。プロジェクトの.mcp.jsonを読むのは、たとえば--scope project付きのclaude mcp addやclaude mcp add-json、claude mcp removeです。カレントディレクトリの.mcp.jsonが通常のファイルでない場合か、2MiBを超えている場合は、これらが終了します。
2.2MBの空白で埋めた.mcp.jsonを置いて、claude mcp removeを実行した結果です。
$ claude mcp remove nothing --scope project
Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.終了コードは1でした。メッセージに出る数値は2097152バイトで、--settingsの2MiBと同じ値です。公式のエラー一覧は、v2.1.257より前の挙動を次のように説明しています。.mcp.jsonの位置にFIFOがあるとコマンドは出力のないまま待ち続け、/dev/zeroへのシンボリックリンクがあるとプロセスが落ちるまでメモリを使い続けました。
直し方は、.mcp.jsonを通常のJSONファイルに置き換えるか、削除してコマンドを再実行することです。
v2.1.214より前との違い
--settingsのサイズ確認が入ったのはv2.1.214からです。
| 観点 | v2.1.213以前 | v2.1.214以降 |
|---|---|---|
| サイズの上限 | v2.1.213以前チェックなし | v2.1.214以降2MiBを超えると起動前に終了 |
数GBのファイルや/dev/zero | v2.1.213以前読み込みを試み、メモリを使い続ける | v2.1.214以降読み込む前に弾かれる |
まとめ
このエラーはsettings.jsonの肥大化ではなく、--settingsが指すファイルの取り違えで起きます。メッセージ末尾のパスを見れば、どちらかがその場で分かります。--settingsはセッション単位の一時的な上書きに向く手段で、恒久設定は4スコープのファイルに置きます。環境変数や実戦のレシピは、Claude Code設定ガイドにあります。
参照した一次ソース
この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。