Error: Settings file exceeds the 2MiB limit

settings.json のサイズが 2MiB（約 209 万バイト）の上限を超えています。Claude Code は上限を超えた設定ファイルを読み込みません。

⭐ メッセージの末尾に、超えているファイルのパスがそのまま出ます。

Error: Settings file exceeds the 2MiB limit: C:\Users\<ユーザー名>\.claude\settings.json

⚠️ どのファイルかを探す必要はありません。 表示されたパスがそのまま対象です（v2.1.238 で実機確認）。パスが読み取れないときだけ、下の「1.」で探してください。

設定ファイルが 2MiB になるのは異常な状態です。手で書いた設定がその大きさになることはまず無いので、何かが自動的に書き込まれ続けていると考えてください。実際に多いのは次の3つです。

🔴 CI と -p では、この警告そのものが出ません

v2.1.238 で 2,200,028 バイト（上限 2,097,152 を超える）の settings.json を置き、 claude -p を実行して実測しました。メッセージは一切出ませんでした。

これは仕様として明記されています。claude --help の -p の説明にこうあります。

Settings files that fail validation are silently ignored in this mode (no error dialog is shown). （このモードでは、検証に失敗した設定ファイルは黙って無視されます。エラーダイアログは表示されません）

⚠️ 非対話になる条件は -p を付けたときだけではありません。

🔴 つまり CI では、設定が丸ごと無視されたまま動きます。 permissions.deny を書いたつもりでも効かず、ログにも何も残りません。

⭐ **上限に近づいていないかは、エラーを待たずに自分で測ってください。**下の「1.」がそのまま使えます。

1. どのファイルが大きいのか特定する（パスが読み取れないときだけ）

settings.json は複数の場所に置けます。メッセージのパスが読めないときは、次で総当たりします。

macOS / Linux

ls -lh ~/.claude/settings.json 2>/dev/null
ls -lh .claude/settings.json 2>/dev/null
ls -lh .claude/settings.local.json 2>/dev/null

Windows（PowerShell）

Get-ChildItem "$env:USERPROFILE\.claude\settings.json", ".claude\settings.json", ".claude\settings.local.json" -ErrorAction SilentlyContinue |
  Select-Object FullName, @{n='MB';e={[math]::Round($_.Length/1MB,2)}}

2. 中身の何が大きいのかを見る

該当ファイルが分かったら、どのキーが太っているのかを確認します。

⚠️ jq は Windows に標準では入っていません。 入っていない環境向けの手順は下の PowerShell 版を使ってください。

macOS / Linux（jq がある場合）

jq -r 'to_entries | map("\(.key)\t\(.value | tostring | length)") | .[]' ~/.claude/settings.json | sort -k2 -n -r | head

jq が無ければ、まず先頭だけ見てあたりを付けます。

head -c 2000 ~/.claude/settings.json

Windows（PowerShell）

$s = Get-Content "$env:USERPROFILE\.claude\settings.json" -Raw -Encoding utf8 | ConvertFrom-Json
$s.PSObject.Properties | ForEach-Object {
  [pscustomobject]@{ Key = $_.Name; Length = ($_.Value | ConvertTo-Json -Compress).Length }
} | Sort-Object Length -Descending | Select-Object -First 10

3. 原因ごとの対処

env に巨大な値が入っている場合

証明書やキーの中身を設定ファイルに直接書かないでください。ファイルのパスを指すのが正しい書き方です。

{
  "env": {
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/company-ca.crt"
  }
}

証明書の内容そのものを値にしていた場合は、ファイルに書き出してパスに置き換えます。

permissions が肥大化している場合

重複した項目を整理します。まず現状を確認してください。

/permissions

同じパターンが何度も並んでいるなら、ワイルドカードでまとめられます。個別のパスを1件ずつ許可し続けると際限なく増えます。

原因が特定できない場合

⚠️ 必ずバックアップを取ってから、既定値に戻します。

macOS / Linux

cp ~/.claude/settings.json ~/.claude/settings.json.bak
rm ~/.claude/settings.json
claude

Windows（PowerShell）

Copy-Item "$env:USERPROFILE\.claude\settings.json" "$env:USERPROFILE\.claude\settings.json.bak"
Remove-Item "$env:USERPROFILE\.claude\settings.json"
claude

Claude Code が起動時に既定の設定を作り直します。バックアップから必要な設定だけを手で戻してください。

4. 分割して持つ

プロジェクト固有の設定は、ユーザー全体の設定と分けます。

分けておくと、1つが肥大化しても影響範囲が閉じます。

• 設定ファイルに「値そのもの」を書かない。 証明書・鍵・大きなJSONはファイルに置いてパスを書く
• 許可設定を個別パスで足し続けない。まとめられるものはパターンで書く
• .claude/settings.local.json は .gitignore に入れておく。肥大化したものをコミットしてチーム全体に配ってしまう事故を防げます
• 設定を書き換えるスクリプトを作るときは、追記ではなく置換にする。追記は必ずいつか溢れます