Error: Settings file not found: <path> の原因と直し方 | Claude Code

エラー文字列

Claude Code

Error: Settings file not found: <path>

⚠️ 標準エラーに出て、終了コードは 1 です。 --version を付けただけでも出ます。設定の読み込みは、認証よりもモデル解決よりも先に行われます。

--settings に渡した値をファイルのパスとして解釈し、そのファイルが無かった状態です。

⭐ --settings はパスと JSON 文字列の両方を受け取ります。 渡された値の見た目からどちらなのかを判断します。ここが、このエラーが分かりにくい理由です。

v2.1.238 で実測した対応表です。

渡した値	出るもの
存在するファイルのパス	（正常に読み込まれる）
存在しないパス	`Error: Settings file not found: <path>`
ディレクトリ	`Error: Cannot use settings file (EISDIR: illegal operation on a directory, read): <path>`
JSON として不正な文字列	`Error: Invalid JSON provided to --settings`
2MiB を超えるファイル	`Error: Settings file exceeds the 2MiB limit`

Windows で最も多い原因です。

--settings '{"env":{"FOO":"bar"}}' のように JSON 文字列を直接渡すとき、シェルが引用符を取り除くと、Claude Code に届く値は {env:{FOO:bar}} になります。

実測では、届いた値の見た目によって出るメッセージが変わりました。

Claude Code に届いた値	出たもの
`{env:{FOO:bar}}`	`Error: Invalid JSON provided to --settings`
`{env:`	`Error: Settings file not found: {env:`

⚠️ Settings file not found: の後ろに、自分が書いた JSON の断片が出ていたら、ファイルの問題ではありません。 引用符がシェルに食われています。

Claude Code は解決後のパスをそのまま表示します。ここが最短の手がかりです。

相対パスは実行時の作業ディレクトリから解決されます。CI やエディタから起動すると、自分がいるつもりの場所とは違うことがあります。

Windows（PowerShell）

claude --settings (Resolve-Path .\team-settings.json).Path -p "..."

macOS / Linux

claude --settings "$(pwd)/team-settings.json" -p "..."

⭐ 引用符の扱いはシェルごとに違います。ファイルに書けばこの問題は起きません。

cat > /tmp/settings.json <<'EOF'
{"env":{"FOO":"bar"}}
EOF
claude --settings /tmp/settings.json -p "..."

どうしても直接渡すなら、シェルに届いた値を先に確認してください。

Windows（PowerShell）

$json = '{"env":{"FOO":"bar"}}'
$json | ConvertFrom-Json | Out-Null   # ここで落ちるなら JSON 自体が不正
claude --settings $json -p "..."

⚠️ cmd.exe から渡す場合、" は \" に書き換える必要があります。 PowerShell から渡すほうが確実です。

--settings ~/.claude のようにディレクトリを渡すと EISDIR になります。 --settings ~/.claude/settings.json のようにファイルまで指定してください。

--settings にはファイルのパスを渡す。 JSON 文字列を直接渡さない
パスは絶対パスにする。相対パスは起動元によって解決先が変わる
CI では、渡す前に test -f "$SETTINGS"（PowerShell なら Test-Path）で存在を確認する
⚠️ 設定ファイルの JSON が壊れていても Claude Code は何も言いません。 存在するだけでは足りないので、JSON として妥当かも併せて検証する