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

このTipsでできること

claude --settingsに渡したファイルが2MiBを超えていると、Claude CodeはError: Settings file exceeds the 2MiB limitで終了コード1になり起動しません。この記事では、なぜこの上限があるのか、実際につまずきやすいパス指定ミスのパターン、--settingsの位置づけをsettings.jsonのスコープ階層の中で解説します。

なぜ「exceeds the 2MiB limit」が出るか

--settingsは、その実行セッション限りで設定を上書きするCLIフラグで、設定JSONファイルへのパス、またはインラインのJSON文字列を受け取ります。指定したキーは通常のsettings.jsonファイル群の同名キーを上書きし、指定しなかったキーはファイル側の値のまま残ります。

このフラグに渡すファイルは「通常のサイズのregular fileであること」という制約があり、上限は2MiBです。settings.jsonは本来、権限ルールや環境変数、MCPサーバー設定を並べた小さなJSONドキュメントなので、この上限を超えるファイルを指定した時点で、パスの指定ミスを疑う価値があります。

Error: Settings file exceeds the 2MiB limit: /path/to/settings.json

エラーメッセージの末尾には、実際に読み込もうとしたファイルの絶対パスが表示されます。まずこのパスが意図したsettings.jsonファイルと一致しているかを確認するのが最初の一手です。

よくある原因

2MiBという上限に実際に到達するケースの多くは、意図した設定ファイルとは別の、大きなファイルを指してしまっているパターンです。

• シェル変数の展開ミス: --settings "$CONFIG_PATH"のような変数展開で、意図せず別のログファイルやビルド成果物のパスが入っている
• ディレクトリを指定してしまう: --settingsにファイルではなくディレクトリを渡すと、2MiB制限とは別にEISDIRという理由でエラーになります(このケースはサイズではなくファイル種別の問題)
• JSON文字列のインライン指定で環境変数を展開しすぎる: --settings "$(env)"のように、意図せず巨大な文字列を生成してそのままインラインJSONとして渡してしまう

なお、--settingsにファイルではないもの(デバイスファイル・FIFO・ソケットなど)を渡した場合は、2MiBのサイズ判定より先にCannot use settings file (Not a regular file (device, FIFO, or socket))というメッセージで弾かれます。/dev/zeroのような無限に読み出せる特殊ファイルを誤って指定してしまうケースが典型です。サイズ判定・regular file判定のどちらもv2.1.214で追加されたチェックで、それより前はこの2つのチェック自体が無く、巨大ファイルや特殊ファイルをそのまま読み込もうとしてメモリを使い切る挙動でした(詳細は後述)。

settings.jsonのスコープと--settingsの位置づけ

「settings.jsonが大きくなりすぎた」という感覚がある場合、まず確認したいのは--settingsと、階層化された通常のsettings.jsonファイル群が別物だという点です。Claude Codeの設定は4つのスコープに分かれています。

--settingsフラグはこの4スコープのどれでもなく、コマンドライン引数による一時的なセッション単位の上書きという第5の経路です。優先順位は「Managed(最上位)→ コマンドライン引数 → Local → Project → User(最下位)」の順で、--settingsで指定した値はLocalやProjectの設定より強く効きます。恒久的な設定をここに置く運用は想定されておらず、CIでの一時的な権限上書きや、テスト用の設定切り替えのような短命の用途に向いています。

実際に2MiBを超えるほど肥大化したsettings.jsonを見直す

まれに、正真正銘の.claude/settings.jsonや~/.claude/settings.json自体が2MiB近くまで育っているケースもあります。この場合に膨らみやすい典型は、permissions.allowルールの列挙が数百行に達している、hooksに長大なインラインスクリプトを直接書き込んでいる、envブロックに大量の変数を並べているといったパターンです。

# ファイルサイズを確認する
ls -la .claude/settings.json
 
# 何が膨らんでいるかをキーごとに見る
jq 'keys' .claude/settings.json

Hooksの本体スクリプトが長い場合は、settings.jsonにインラインで書かず、外部スクリプトファイルへ切り出してパスだけを設定に書く形に分離すると、設定ファイル自体のサイズと可読性の両方が改善します。permissionsルールが大量になっている場合は、個別ルールの列挙よりも、ディレクトリ単位でまとめられないかを見直す余地があります。

もっとも、実運用でsettings.jsonそのものが2MiBに達することはほとんどありません。2MiBという上限に到達している場合は、設定内容そのものより、ファイルの取り違えを先に疑うのが合理的です。誤ってビルドキャッシュやログの出力先を--settingsのパスとして環境変数に設定していないか、シェルのヒストリやCIの環境変数定義を確認する価値があります。

起動時に読み込まれる設定ファイルの全体像

--settingsのエラーに遭遇したタイミングで、settings.jsonがどう組み立てられているか全体像を掴んでおくと、次に別の設定トラブルに当たったときの見通しが良くなります。Claude Codeは起動時に、上記4スコープのsettings.jsonファイルを走査し、それぞれのファイルに書かれたキーをマージします。同じキーが複数のスコープに存在する場合は前述の優先順位に従って1つの値に決まりますが、permissionsのルールだけは例外で、上書きではなく複数スコープの内容がマージされます。Managed scopeで強制されたルールは、コマンドライン引数を含む他のどのスコープからも上書きできません。

この仕組みを踏まえると、--settingsで一時的に上書きしたい設定と、Managed scopeで固定されているセキュリティ上重要な設定は別物だと分かります。--settingsで緩めた権限がManagedのルールと衝突する場合、Managedのルールが優先されるため、意図した上書きが効かないという別の混乱につながることもあります。個人・チーム・企業のレイヤー別に権限設計をどこまで固定するかの考え方はClaude Codeセキュリティ・権限ガイドにまとめています。

CIでの一時的な上書きとして使う

--settingsが向いているのは、恒久的な設定ではなく「このセッションだけ」の一時的な上書きです。典型例は、CIパイプラインの中で通常より緩い権限モードを一時的に有効にしたいケースや、複数の設定パターンをテストで切り替えたいケースです。

claude -p "このPRの差分をレビューして" \
  --settings '{"permissions":{"defaultMode":"acceptEdits"}}'

このように、インラインのJSON文字列として直接渡す使い方であれば、そもそも巨大なファイルを参照する経路自体が存在しないため2MiBエラーには到達しません。2MiBエラーが出るのは、--settingsにファイルパスを渡す形で使っていて、かつそのパスが意図と違うファイルを指しているケースです。ファイルパスを渡す運用にしている場合は、CIの実行ログにパスをそのまま出力しておくと、次に同じエラーが出たときの切り分けが速くなります。

v2.1.214より前とどう変わったか

--settingsのファイルサイズチェックは、Claude Code v2.1.214で追加されました。

v2.1.213以前は、誤って巨大なファイルパスを--settingsに渡すと、Claude Codeがそのままファイル全体を読み込もうとし、マシンのメモリを圧迫する形で問題が表面化していました。v2.1.214からは起動直後の軽量なチェックで弾かれるため、原因の特定がエラーメッセージ1行で完結するようになっています。

よくある質問

通常のsettings.jsonにも2MiB制限はありますか

公式ドキュメントで明記されているのは--settingsフラグに渡すファイルへの制限です。~/.claude/settings.jsonや.claude/settings.jsonが肥大化している場合は、前述のとおりHooksスクリプトの外部化やpermissionsルールの整理を検討する価値があります。

ディレクトリを指定した場合も2MiBエラーになりますか

いいえ。ディレクトリを--settingsに渡した場合は、サイズ判定より先にEISDIRという理由のエラーになります。デバイスファイルやFIFO、ソケットを渡した場合も同様に、サイズ判定の前に「regular fileではない」という理由で弾かれます。

--settingsにJSON文字列を直接渡す場合も2MiBは関係しますか

--settingsはファイルパスとインラインJSON文字列の両方を受け付けます。インラインJSON文字列が2MiBに達するケースは通常考えにくいですが、シェルの変数展開で意図せず巨大な文字列を生成してしまうと同じ制限に触れる可能性があります。

エラーになったときの終了コードは

1です。CIスクリプトで--settingsを使う場合、この終了コードを起動失敗の判定に使えます。

まとめ

Settings file exceeds the 2MiB limitは、--settingsフラグに渡したパスが2MiB超のファイルを指しているときに、起動直後の軽量チェックで出るエラーです。エラーメッセージ末尾のパスが意図したsettings.jsonと一致しているかをまず確認し、シェル変数の展開ミスやディレクトリ指定の混同がないかを疑うのが早道です。

--settingsはManaged・Project・User・Localの4スコープとは別枠の、セッション単位の一時的な上書き経路だと理解しておくと、恒久設定との使い分けで迷いにくくなります。v2.1.214からはサイズとファイル種別のチェックが起動直後に走るため、原因の切り分けはエラーメッセージを読むだけでほぼ完結します。settings.json全体の項目や権限設計はClaude Code settings.json完全ガイド、環境変数や実戦レシピはClaude Code設定ガイドを参照してください。