「path names a network location」の原因と対処 — Claude Code

Claude Codeの書き込みやコマンドが「the path is network-shaped」というメッセージで止まったときは、パスの綴りが原因です。worktreeで隔離されたセッションが、UNC共有(\\server\share\file)や/net自動マウント、手元に無いドライブ文字のパスを指定すると、ガードが操作を止めます。

似た文言に「cannot be safely resolved」がありますが、促される直し方が違います。この記事では2つの見分け方と、待てば直る場合・実体を決め直す場合の切り分けを示します。/add-dirでUNC共有を追加できない場合は別の仕様です。

どちらのメッセージが出ているか

worktree隔離のガードは、書き込みとコマンドの作業ディレクトリが、隔離の外にある共有チェックアウトへ届かないかを調べます。シンボリックリンクを解決してから判定し、判定できなければ操作を止める作りです。止めたときの文言は2種類あります。

見分ける手がかりは、文言に「network-shaped」があるかどうかです。「cannot be safely resolved」の例示にもネットワーク共有の形が入っているので、共有パスを指定して前者が出ることもあります。どちらも、ファイルの実体がworktree内にあるなら、その実パスで指定し直すという方向です。

このガードは以前から常にあったわけではありません。v2.1.217より前は、パスの文字列だけを比べていました。UNCや/netの形でチェックアウト内のファイルを指定しても、止められなかったのです。アップデート後に急にブロックされ始めたなら、この変更が理由の1つです。

ガードが働くのはどんなセッションか

対象は、worktreeに隔離されたセッション全般です。対話型でもバックグラウンドでも、同じ規則が適用されます。隔離の入口は3つあります。

• --worktree(-w)を付けて起動した
• ClaudeがEnterWorktreeツールでworktreeに入った
• worktreeで終わったセッションを再開した

隔離されたセッションがつくるサブエージェントも、同じ検査を受けます。サブエージェントの定義にisolation: worktreeを書いた場合も同様です。隔離なしの通常の対話セッションでは、このガードは働きません。

worktreeを再開するときは、記録されたパスがネットワーク綴りだとits recorded path has a network spellingと表示されます。Claude Codeはネットワーク上のパスのworktreeには再開しないので、ローカルのパスにworktreeを作り直します。

隔離の検査は4種類あり、ネットワーク形の綴りが関わるのは2つです。Edit・Write・NotebookEditが主チェックアウトのパスを狙う検査と、Bash・PowerShell・Monitorの作業ディレクトリを検証する検査です。残る2つはgitの向き先と、コマンド文の形を調べます。PowerShellのコマンドに働くのは、作業ディレクトリの検査だけです。検査の対象は、起動したリポジトリと、リンクされたworktreeの元になった主チェックアウトです。ブロックはツールエラーとしてClaudeに届き、worktreeの名前と進め方が添えられます。

バックグラウンドセッションは、既定でこの隔離に入ります。v2.1.289のclaude --helpでは、worktreeと追加ディレクトリの指定は次のように出ます。

claude --help | grep -A1 -E "^\s+(-w, --worktree|--add-dir)"

  --add-dir <directories...>            Additional directories to allow tool
                                        access to
--
  -w, --worktree [name]                 Create a new git worktree for this
                                        session (optionally specify a name)

待てば直るのか、実体を決め直すのか

多くの場合、手を動かす必要はありません。エラーの全文はツールエラーとしてClaudeに渡り、Claudeがローカルの綴りで再試行します。繰り返し止まるときだけ、次の順に切り分けます。

同じ綴りを拒む3つの場面

ネットワーク形のパスを断る仕組みは、worktreeのガードだけではありません。場面ごとに表示が違うので、メッセージの文言から場面を特定できます。

worktreeのガードは、そのパスが共有チェックアウトの外にあると確かめられないため止めます。

--add-dirとArtifact公開が拒む理由は、ネットワークパスを調べるだけで、パスが指すホストに接続してしまう点にあります。Windowsでは、その接続で資格情報が相手ホストへ送られる場合があります。--add-dirの側は、調べる前にパスを断ります。マップしたドライブ文字と\\wsl$のパスは、ネットワークパスに数えません。/net/<host>は、そのホストの自動マウント配下から起動した場合に限って通ります。

リンク経由の指定も同じ扱いです。ローカルのパスでも、シンボリックリンクやジャンクションの先がネットワーク上なら、--add-dirは拒否します。/add-dirで指定したときだけでなく、起動時の警告としても同じ拒否が出ます。起動時なら、Claude Codeはそのディレクトリを加えずに立ち上がります。Windowsでは、メッセージが「共有をドライブ文字に割り当て、起動時に--add-dirで渡す」よう案内します。ドライブ文字を途中で加えても、リモート読み取りの信頼は付かないと書かれています。

Windowsの\??\というNTデバイスのプレフィックスがUNCの検証をすり抜ける問題は、v2.1.233で直りました。資格情報が漏れうる経路を閉じる修正です。

worktree.bgIsolationを"none"にするとどうなるか

隔離をやめると、このガードの前提が消えます。ガードは、worktreeに隔離されている間のセッションに対して働くからです。

バックグラウンドセッションの既定値は"worktree"です。EnterWorktreeを呼ぶまで、共有チェックアウトへのEditとWriteが止まります。"none"にすると、バックグラウンドのジョブはworktreeに入らず、作業コピーを直接編集します。

{
  "worktree": {
    "bgIsolation": "none"
  }
}

この設定は、gitのworktreeが使いにくいリポジトリ向けです。並列のセッションが同じ作業コピーに書き込むことになる点は変わります。←や/backgroundでバックグラウンドへ移した既存セッションは、設定にかかわらず元の場所で編集を続けます。--add-dir側の拒否は別の仕組みなので、"none"でも残ります。

設定の全項目はClaude Code settings.json完全ガイドにあります。worktree運用全体はClaude Code Worktree実践ガイドで扱っています。

WindowsのUNCパスとWebDAV

UNC形式のパス(\\server\share)はWindowsで多く使われるため、このエラーもWindowsで出会いやすくなります。書き込みブロックとは別に、セキュリティ文書はWebDAVについて注意を促しています。

WebDAVが有効で、Claude Codeが\\*のようなパスに触れられると、権限システムを通らずにリモートホストへのネットワークリクエストが起こりえます。そのためWindowsでは、WebDAVを有効にしない、またはWebDAVのサブディレクトリを含みうるパスへのアクセスを許可しないことが推奨されています。MicrosoftはWebDAV(Webclientサービス)自体を非推奨にしています。

Windowsには、リンクを含むworktreeの後始末に関する記述もあります。worktree内のフォルダーがNTFSジャンクションやディレクトリシンボリックリンクなら、worktreeを消してもリンクだけが消え、リンク先のフォルダーは残ります。v2.1.205より前は、サブディレクトリ内のリンクが指すフォルダーまで消えることがありました。

macOS・Linuxの/netと、手元に無いドライブ文字

/net自動マウントはmacOSとLinuxにも存在するので、UNC共有ほど多くはなくても起こりえます。ネットワークファイルシステムを自動マウントで使う環境では、ローカルの綴りでパスを渡すことになります。

「手元に無いドライブ」は、たとえば次の状況です。自分のマシンでZ:\に共有を割り当てて使っていて、CI環境やリモート環境のセッションが同じZ:\で指定する場合です。ローカルでは普通のパスでも、セッション側のマシンにそのドライブが無ければ、ネットワーク形のパスとして止まります。

まとめ

文言に「network-shaped」が出たら、隔離セッションの中でネットワーク形の綴りが使われています。まずはClaudeの再試行に任せ、繰り返すときは、ファイルの実体がworktree内か共有上かを先に決めると、直す方向が定まります。