Claude Media
Claude Code settings 2MiBエラーの直し方 — settings.json肥大化の対処

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/zero

3つとも終了コードは1でした。/dev/zeroは無限に読み出せるため、v2.1.214より前は読み込みが止まらずメモリを使い続けました。いまは読み込みの前に弾かれ、doctorも走りません。

境界はちょうど2,097,152バイト

2MiBは2,097,152バイトです。中身が{}で残りを空白で埋めた2つのファイルで、境界を測りました。

くらべる

1バイトで分かれる境界

2MiBちょうど

2,097,152バイト

読み込めてdoctorが動きます(終了コード0)。

1バイト超過

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 2097152

CIスクリプトでは終了コードが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/zerov2.1.213以前読み込みを試み、メモリを使い続けるv2.1.214以降読み込む前に弾かれる

まとめ

このエラーはsettings.jsonの肥大化ではなく、--settingsが指すファイルの取り違えで起きます。メッセージ末尾のパスを見れば、どちらかがその場で分かります。--settingsはセッション単位の一時的な上書きに向く手段で、恒久設定は4スコープのファイルに置きます。環境変数や実戦のレシピは、Claude Code設定ガイドにあります。

参照した一次ソース

この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。

  1. code.claude.com/docs/en/errors
  2. code.claude.com/docs/en/cli-reference
  3. code.claude.com/docs/en/settings
この記事を共有:XはてブLinkedIn