「cannot be safely resolved」の原因と対処 — Claude Code

Claude Codeでファイルの書き込みやコマンド実行が「path is spelled in a form that cannot be safely resolved」で止まることがあります。これはworktreeで隔離されたセッションが、シンボリックリンクなど解決しきれないパスを経由して共有チェックアウトへ書き込むのを防ぐガードの動作です。ほとんどの場合Claude自身が直接パスで再試行して自動的に解消するため、通常はこちらで何かする必要はありません。同じファイルで繰り返す場合だけ、下の対処法を確認してください。

「cannot be safely resolved」エラーとは

このエラーは、worktreeで隔離されたセッション(バックグラウンドか対話かを問わない)や、worktreeで隔離されたサブエージェントが、1か所に検証できないパスでファイルやコマンドの作業ディレクトリを指定したときに出ます。ガードは操作前にシンボリックリンクを解決し、その結果が共有チェックアウトに届かないことを確認します。解決自体に失敗した場合は、安全側に倒して操作そのものをブロックします。

実際のメッセージは次の内容です。

コマンド実行がブロックされた場合も原因は同じで、対象が作業ディレクトリになり、メッセージの末尾は「re-run the command from its direct symlink-free path」に変わります。

どんな形のパスがブロックされるか

メッセージが例示するのは3パターンです。1つ目は、生の..セグメントを保持したシンボリックリンク経由のパス。2つ目は、ネットワーク共有やデバイス名前空間の形をしたパス。3つ目は、途中の階層に読み取れないディレクトリを含むパスです。いずれも「このパスをたどった先が本当に共有チェックアウトの外にあるか」をガードが機械的に確認しきれない形です。

もっとも起こりやすいのは1つ目のシンボリックリンクのケースです。たとえば docs/current -> ../README.md のように、リンク先に .. を含むシンボリックリンクがリポジトリにコミットされていると、そのリンクを通した書き込みはこのエラーの対象になります。ドキュメントの「最新版」を指すエイリアスや、設定ファイルの共有によく使われる形なので、モノレポや複数パッケージ構成のリポジトリで踏みやすいパターンです。

3パターンの違いを早見表にまとめます。

いずれも共通しているのは、パスの文字列表現と実際の到達先が一致する保証をガード側が機械的に得られない、という点です。

なぜこのガードが必要なのか

Claude Codeはバックグラウンドセッションを、実行前に専用のgit worktreeへ隔離します。同じチェックアウトを複数のセッションが同時に読みつつ、書き込みだけは各自のworktreeに閉じ込めることで、並列実行中の競合を防ぐ仕組みです。この隔離が機能するには、「このパスは自分のworktreeの中にあるか、それとも共有チェックアウトに届いてしまうか」をガードが正確に判定できる必要があります。

シンボリックリンクやネットワークパスは、見た目のパス文字列と実際の到達先が一致しないため、文字列だけの比較では判定を誤ります。v2.1.217より前のガードはパスのつづりだけを比較していたため、シンボリックリンク経由の書き込みが共有チェックアウトまで届いてしまうことがありました。v2.1.217からはシンボリックリンクを解決したうえで判定するようになり、解決自体に失敗するケースは「わからないので通さない」という安全側の判断でブロックするようになっています。

対処法

通常はこちらで何かする必要はありません。エラーの全文はツールエラーとしてClaude自身に渡り、Claudeはメッセージが示す直接パスで自動的に再試行します。ファイル編集がブロックされた場合、会話画面には短い Error editing file という表示しか出ませんが、Ctrl+O で開くトランスクリプト表示には全文が残ります。コマンドがブロックされた場合は、コマンドの出力にそのまま全文が表示されます。

同じファイルで繰り返しブロックが起こる場合は、docs/current -> ../README.md のようにリンク先に .. を含む、コミット済みのシンボリックリンクが原因である可能性が高いです。そうしたリンクが対象ファイルの経路上にないか確認し、Claudeにはシンボリックリンクではなく実体ファイルの直接パスを編集するよう指示してください。

# リポジトリ内のシンボリックリンクを洗い出す
find . -type l -not -path "./.git/*"

洗い出したリンクの readlink 結果に .. が含まれていれば、それが原因の候補です。可能であればリンクを実体パスへの直接参照に置き換えるか、Claudeへの指示でリンクを経由しないパスを明示すると再発を防げます。

worktree隔離を無効化する設定との関係

worktreeによる隔離自体は worktree.bgIsolation 設定で切り替えられます。デフォルトの "worktree" では EnterWorktree ツールを呼ぶまで共有チェックアウトへの Edit・Write がブロックされ、このガードもその隔離の一部として働きます。"none" に変更するとバックグラウンドジョブは作業コピーを直接編集するようになり、worktree自体を経由しなくなります。ただしこの設定はgit worktreeへの隔離をやめるだけで、シンボリックリンク解決の判定ロジックそのものを無効化するものではありません。設定の全項目はClaude Code settings.json完全ガイドにまとめています。

サブエージェントを独自のworktreeに隔離したい場合は、frontmatterで isolation: worktree を指定するか、起動時に isolation: "worktree" を渡します。この設定を使ったサブエージェントも、同じガードの対象になります。worktree運用全体の考え方はClaude Code Worktree実践ガイドで解説しています。

worktree.symlinkDirectoriesとの切り分け

設定名が似ているため、worktree.symlinkDirectories と混同しないよう注意してください。この設定は node_modules や .cache のような大きなディレクトリを各worktreeに複製せず、メインリポジトリからシンボリックリンクとして張るためのものです。デフォルトではどのディレクトリもリンクされません。

この設定が作るシンボリックリンクはツール自身が生成したものであり、メッセージが警告する「ドットセグメントを保持したシンボリックリンク」の形にはなりません。そのため、worktree.symlinkDirectories で張ったリンクを経由した読み書きは、通常このガードの対象にはなりません。ガードが実際に問題にするのは、リポジトリにコミットされていて .. のような相対パスを含む、人が手で作ったシンボリックリンクです。両者は「worktreeとシンボリックリンクが絡む」という表面上の共通点があるだけで、発生する場面もエラーの原因も別物だと考えてください。

よくある質問

エラーが出たら作業は失敗しますか

その場では失敗しますが、Claudeは通常メッセージが示す直接パスで即座に再試行します。人が介入しなくても解消するケースがほとんどです。

エラーメッセージの全文はどこで見られますか

ファイル編集がブロックされた場合は会話画面に短い表示しか出ないため、Ctrl+O でトランスクリプト表示を開いてください。コマンド実行のブロックはコマンド出力にそのまま全文が表示されます。

worktreeを使っていない対話セッションでも起こりますか

起こりません。このガードはworktreeで隔離されたセッション、またはworktreeで隔離されたサブエージェントだけが対象です。隔離を伴わない通常の対話セッションでは判定自体が働きません。

読み取れないディレクトリとは具体的にどんな状態ですか

途中の階層に権限不足でアクセスできないディレクトリが挟まっている状態です。パーミッションの都合で stat に失敗すると、その先が安全かどうか確認できず、シンボリックリンクと同じ扱いでブロックされます。

worktree.symlinkDirectoriesを設定していると起こりやすくなりますか

worktree.symlinkDirectories が作るリンクはツールが生成した単純な形なので、それ自体がこのガードに引っかかることは通常ありません。起こりやすさが変わるとしたら、node_modules のような大きなディレクトリをリンクで共有する運用に慣れているリポジトリほど、コミット済みシンボリックリンクにも気づきにくくなる、という間接的な話にとどまります。

まとめ

「cannot be safely resolved」は、worktreeで隔離されたセッションやサブエージェントが、シンボリックリンク・ネットワークパス・読み取れないディレクトリのいずれかを経由してパスを指定したときに出るガードです。多くはClaudeが直接パスで自動的に再試行して解消します。同じファイルで繰り返す場合は、.. を含むコミット済みシンボリックリンクが原因になっていないか確認してください。