fix: print NFS workaround hint when uv pip install/sync fails (#417)

Author: bigcat88

comfy_cli/uv.py

@@ -18,7 +18,21 @@ def _run(cmd: list[str], cwd: PathLike, check: bool = True) -> subprocess.Comple
 def _check_call(cmd: list[str], cwd: PathLike | None = None):
     """uses check_call to run pip, as reccomended by the pip maintainers.
     see https://pip.pypa.io/en/stable/user_guide/#using-pip-from-your-program"""
-    subprocess.check_call(cmd, cwd=cwd)
+    try:
+        subprocess.check_call(cmd, cwd=cwd)
+    except subprocess.CalledProcessError:
+        if len(cmd) >= 5 and cmd[1:4] == ["-m", "uv", "pip"] and cmd[4] in ("install", "sync"):
+            from rich import print as rprint
+
+            rprint(
+                "\n[bold yellow]Hint:[/bold yellow] If you are on a network filesystem "
+                "(RunPod, NFS, etc.), this may be caused by a known uv issue.\n"
+                "Try setting one of these environment variables before running comfy:\n"
+                "  [green]export UV_LINK_MODE=copy[/green]\n"
+                "  [green]export UV_CACHE_DIR=<your-workspace>/.cache/uv[/green]\n"
+                "See https://github.com/astral-sh/uv/issues/12036 for details."
+            )
+        raise
 
 
 _req_name_re: re.Pattern[str] = re.compile(r"require\s([\w-]+)")

tests/uv/test_uv.py

@@ -1,12 +1,13 @@
 import shutil
+import subprocess
 from pathlib import Path
 from unittest.mock import patch
 
 import pytest
 
 from comfy_cli import ui
 from comfy_cli.constants import GPU_OPTION
-from comfy_cli.uv import DependencyCompiler
+from comfy_cli.uv import DependencyCompiler, _check_call
 
 hereDir = Path(__file__).parent.resolve()
 mockComfyDir = hereDir / "mock_comfy"
@@ -302,3 +303,60 @@ def test_skip_torch_install_deps_no_extra_index_url():
         depComp.install_deps()
     cmd = mock_check_call.call_args[0][0]
     assert "--extra-index-url" not in cmd
+
+
+def test_check_call_prints_nfs_hint_on_uv_install_failure(capsys):
+    """When a uv pip install command fails, _check_call should print an NFS hint."""
+    cmd = ["python", "-m", "uv", "pip", "install", "--requirement", "reqs.txt"]
+    with patch("subprocess.check_call", side_effect=subprocess.CalledProcessError(2, cmd)):
+        with pytest.raises(subprocess.CalledProcessError):
+            _check_call(cmd)
+
+    captured = capsys.readouterr().out
+    assert "network filesystem" in captured
+    assert "UV_LINK_MODE" in captured
+    assert "UV_CACHE_DIR" in captured
+
+
+def test_check_call_prints_nfs_hint_on_uv_sync_failure(capsys):
+    """When a uv pip sync command fails, _check_call should print an NFS hint."""
+    cmd = ["python", "-m", "uv", "pip", "sync", "reqs.txt"]
+    with patch("subprocess.check_call", side_effect=subprocess.CalledProcessError(2, cmd)):
+        with pytest.raises(subprocess.CalledProcessError):
+            _check_call(cmd)
+
+    captured = capsys.readouterr().out
+    assert "network filesystem" in captured
+
+
+def test_check_call_no_hint_for_non_uv_failure(capsys):
+    """Non-uv commands should not trigger the NFS hint."""
+    cmd = ["python", "-m", "pip", "install", "requests"]
+    with patch("subprocess.check_call", side_effect=subprocess.CalledProcessError(1, cmd)):
+        with pytest.raises(subprocess.CalledProcessError):
+            _check_call(cmd)
+
+    captured = capsys.readouterr().out
+    assert "network filesystem" not in captured
+
+
+def test_check_call_no_hint_on_uv_compile_failure(capsys):
+    """uv pip compile failures should not trigger the NFS hint (only install/sync)."""
+    cmd = ["python", "-m", "uv", "pip", "compile", "reqs.in"]
+    with patch("subprocess.check_call", side_effect=subprocess.CalledProcessError(1, cmd)):
+        with pytest.raises(subprocess.CalledProcessError):
+            _check_call(cmd)
+
+    captured = capsys.readouterr().out
+    assert "network filesystem" not in captured
+
+
+def test_check_call_no_hint_for_pip_install_uv(capsys):
+    """'pip install uv' must not trigger the hint even though 'uv' and 'install' are both present."""
+    cmd = ["python", "-m", "pip", "install", "--upgrade", "pip", "uv"]
+    with patch("subprocess.check_call", side_effect=subprocess.CalledProcessError(1, cmd)):
+        with pytest.raises(subprocess.CalledProcessError):
+            _check_call(cmd)
+
+    captured = capsys.readouterr().out
+    assert "network filesystem" not in captured