fix: surface devbox docker/kubeconfig errors as ClickException (#1041)

## Summary
- Wrap the docker volume/ps subprocess calls in `_devbox.py` with a
small `_run_docker` helper that converts non-zero exits into
`click.ClickException` with stderr details, instead of bubbling raw
`CalledProcessError` up the stack.
- Use `unlink(missing_ok=True)` and translate `PermissionError` on the
stale k3s kubeconfig into an actionable `ClickException`.

## Closes
- [FLYTE-SDK-D](https://unionai.sentry.io/issues/FLYTE-SDK-D) — `docker
volume ls` non-zero exit reported as raw subprocess crash
- [FLYTE-SDK-1H](https://unionai.sentry.io/issues/FLYTE-SDK-1H) —
`PermissionError` unlinking `/tmp/.kube/kubeconfig`

## Test plan
- [x] New unit tests in `tests/cli/test_devbox.py` cover the failure
paths for `_ensure_volume`, `_container_is_running`,
`_container_is_paused`.
- [x] Existing devbox tests still pass.
- [ ] Manual: \`flyte start devbox\` with docker stopped → friendly
message; with a root-owned `/tmp/.kube/kubeconfig` → friendly message.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Signed-off-by: Haytham Abuelfutuh <haytham@afutuh.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: EngHabu

src/flyte/cli/_devbox.py

@@ -36,29 +36,37 @@ def _ensure_docker_available() -> None:
         )
 
 
+def _run_docker(cmd: list[str], failure_message: str) -> subprocess.CompletedProcess:
+    """Run a docker command and translate failure into a user-facing ClickException."""
+    result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    if result.returncode != 0:
+        details = (result.stderr or result.stdout or "").strip()
+        raise click.ClickException(f"{failure_message}\n{details}" if details else failure_message)
+    return result
+
+
 def _ensure_volume(volume_name: str) -> None:
-    result = subprocess.run(
+    result = _run_docker(
         ["docker", "volume", "ls", "--filter", f"name=^{volume_name}$", "--format", "{{.Name}}"],
-        capture_output=True,
-        text=True,
-        check=True,
+        f"Failed to list docker volumes while checking for '{volume_name}'.",
     )
     if volume_name not in result.stdout:
-        subprocess.run(["docker", "volume", "create", volume_name], check=True)
+        _run_docker(
+            ["docker", "volume", "create", volume_name],
+            f"Failed to create docker volume '{volume_name}'.",
+        )
 
 
 def _container_is_running(container_name: str) -> bool:
-    result = subprocess.run(
+    result = _run_docker(
         ["docker", "ps", "--filter", f"name=^{container_name}$", "--format", "{{.Names}}"],
-        capture_output=True,
-        text=True,
-        check=True,
+        f"Failed to query docker for container '{container_name}'.",
     )
     return container_name in result.stdout
 
 
 def _container_is_paused(container_name: str) -> bool:
-    result = subprocess.run(
+    result = _run_docker(
         [
             "docker",
             "ps",
@@ -69,9 +77,7 @@ def _container_is_paused(container_name: str) -> bool:
             "--format",
             "{{.Names}}",
         ],
-        capture_output=True,
-        text=True,
-        check=True,
+        f"Failed to query docker for paused container '{container_name}'.",
     )
     return container_name in result.stdout
 
@@ -258,8 +264,13 @@ def launch_devbox(image_name: str, is_dev_mode: bool, gpu: bool = False, log_for
 
     _KUBE_DIR.mkdir(parents=True, exist_ok=True)
     # This step makes sure that we always used the latest k3s kubeconfig file
-    if _KUBECONFIG_PATH.exists():
-        _KUBECONFIG_PATH.unlink()
+    try:
+        _KUBECONFIG_PATH.unlink(missing_ok=True)
+    except PermissionError as e:
+        raise click.ClickException(
+            f"Permission denied removing stale kubeconfig at {_KUBECONFIG_PATH}. "
+            f"Delete it manually (e.g. `sudo rm {_KUBECONFIG_PATH}`) and retry.\n{e}"
+        )
 
     steps = _STEPS_DEV if is_dev_mode else _STEPS
 

tests/cli/test_devbox.py

@@ -181,3 +181,39 @@ def test_explicit_image_with_gpu_is_respected(self):
             result = runner.invoke(devbox, ["--gpu", "--image", "myorg/custom:latest"])
             assert result.exit_code == 0, result.output
             assert mock_launch.call_args.args[0] == "myorg/custom:latest"
+
+
+class TestDockerSubprocessFailures:
+    """Docker CLI failures should surface as click.ClickException, not raw CalledProcessError."""
+
+    def test_ensure_volume_failure_raises_click_exception(self):
+        import click
+
+        from flyte.cli._devbox import _ensure_volume
+
+        with patch("flyte.cli._devbox.subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=1, stdout="", stderr="docker daemon not reachable")
+            with pytest.raises(click.ClickException) as excinfo:
+                _ensure_volume("flyte-devbox")
+            assert "Failed to list docker volumes" in str(excinfo.value.message)
+            assert "docker daemon not reachable" in str(excinfo.value.message)
+
+    def test_container_is_running_failure_raises_click_exception(self):
+        import click
+
+        from flyte.cli._devbox import _container_is_running
+
+        with patch("flyte.cli._devbox.subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=1, stdout="", stderr="boom")
+            with pytest.raises(click.ClickException):
+                _container_is_running("flyte-devbox")
+
+    def test_container_is_paused_failure_raises_click_exception(self):
+        import click
+
+        from flyte.cli._devbox import _container_is_paused
+
+        with patch("flyte.cli._devbox.subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=1, stdout="", stderr="boom")
+            with pytest.raises(click.ClickException):
+                _container_is_paused("flyte-devbox")