fix: wrap docker buildx ls/create failures as ImageBuildError

`docker buildx create --name flytex ...` (and `docker buildx ls`) run with
`check=True`, so a CalledProcessError bubbled out of `_ensure_buildx_builder`
raw and was reported to Sentry as an SDK crash (FLYTE-SDK-4R) even though the
failure is a local Docker environment problem (daemon down, driver missing, or
a leftover/locked builder), not an SDK bug.

Wrap both subprocess calls in `ImageBuildError` (a `RuntimeUserError`, filtered
from Sentry) with an actionable message that includes the captured stderr and
points at `docker buildx rm flytex` / the remote image builder. If the create
fails because the builder already exists (concurrent build), reuse it instead
of failing.

fixes FLYTE-SDK-4R

Signed-off-by: Haytham Abuelfutuh <haytham@afutuh.com>

Author: EngHabu

src/flyte/_internal/imagebuild/docker_builder.py

@@ -688,9 +688,16 @@ async def _ensure_buildx_builder():
             raise ImageBuildError("Docker buildx is not available. Make sure BuildKit is installed and enabled.")
 
         # List builders
-        result = await run_sync_with_loop(
-            subprocess.run, ["docker", "buildx", "ls"], capture_output=True, text=True, check=True
-        )
+        try:
+            result = await run_sync_with_loop(
+                subprocess.run, ["docker", "buildx", "ls"], capture_output=True, text=True, check=True
+            )
+        except subprocess.CalledProcessError as e:
+            raise ImageBuildError(
+                f"Failed to list docker buildx builders: {(e.stderr or '').strip() or e}. "
+                "Ensure the Docker daemon is running, or use the remote image builder by setting "
+                "`image_builder='remote'` on your `flyte.Image`."
+            ) from e
         builders = result.stdout
 
         # Check if there's any usable builder with the correct driver options
@@ -716,21 +723,39 @@ async def _ensure_buildx_builder():
         else:
             logger.info("No buildx builder found, creating one...")
 
-        await run_sync_with_loop(
-            subprocess.run,
-            [
-                "docker",
-                "buildx",
-                "create",
-                "--name",
-                DockerImageBuilder._builder_name,
-                "--platform",
-                "linux/amd64,linux/arm64",
-                "--driver-opt",
-                "network=host",
-            ],
-            check=True,
-        )
+        # Create the builder. Wrap subprocess failures in ImageBuildError so a broken or
+        # locked Docker environment surfaces as an actionable user error instead of leaking
+        # as a raw CalledProcessError crash report (FLYTE-SDK-4R).
+        try:
+            await run_sync_with_loop(
+                subprocess.run,
+                [
+                    "docker",
+                    "buildx",
+                    "create",
+                    "--name",
+                    DockerImageBuilder._builder_name,
+                    "--platform",
+                    "linux/amd64,linux/arm64",
+                    "--driver-opt",
+                    "network=host",
+                ],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+        except subprocess.CalledProcessError as e:
+            stderr = (e.stderr or "").strip()
+            # A concurrent build may have created the builder between our `ls` check and now;
+            # if it already exists we can just reuse it instead of failing.
+            if "already exists" in stderr.lower():
+                logger.info(f"Buildx builder {DockerImageBuilder._builder_name!r} already exists, reusing it.")
+                return
+            raise ImageBuildError(
+                f"Failed to create docker buildx builder {DockerImageBuilder._builder_name!r}: {stderr or e}. "
+                f"Try removing it with `docker buildx rm {DockerImageBuilder._builder_name}`, or use the remote "
+                "image builder by setting `image_builder='remote'` on your `flyte.Image`."
+            ) from e
 
     async def _build_image(self, image: Image, *, push: bool = True, dry_run: bool = False, wait: bool = True) -> str:
         """

tests/flyte/imagebuild/test_docker_builder.py

@@ -883,6 +883,78 @@ def mock_run(cmd, **kwargs):
     assert "network=host" in create_cmds[0]
 
 
+@pytest.mark.asyncio
+async def test_ensure_buildx_builder_wraps_create_failure_as_image_build_error():
+    """When `docker buildx create` fails, the raw CalledProcessError should not bubble out.
+
+    Previously this leaked into Sentry as a RuntimeSystem/CalledProcessError crash report
+    (FLYTE-SDK-4R). It should be wrapped in an actionable ImageBuildError, which is filtered.
+    """
+    from flyte.errors import ImageBuildError
+
+    def mock_run(cmd, **kwargs):
+        result = subprocess.CompletedProcess(cmd, 0)
+        if cmd == ["docker", "buildx", "ls"]:
+            result.stdout = "default"
+            result.stderr = ""
+            return result
+        if "create" in cmd:
+            raise subprocess.CalledProcessError(returncode=1, cmd=cmd, stderr="ERROR: failed to find driver")
+        return result
+
+    with patch(
+        "flyte._internal.imagebuild.docker_builder.run_sync_with_loop", side_effect=lambda fn, *a, **kw: fn(*a, **kw)
+    ):
+        with patch("subprocess.run", side_effect=mock_run):
+            with pytest.raises(ImageBuildError, match="Failed to create docker buildx builder"):
+                await DockerImageBuilder._ensure_buildx_builder()
+
+
+@pytest.mark.asyncio
+async def test_ensure_buildx_builder_reuses_existing_on_already_exists():
+    """If `docker buildx create` fails because the builder already exists (e.g. a concurrent
+    build created it), it should be reused rather than raising."""
+
+    def mock_run(cmd, **kwargs):
+        result = subprocess.CompletedProcess(cmd, 0)
+        if cmd == ["docker", "buildx", "ls"]:
+            result.stdout = "default"
+            result.stderr = ""
+            return result
+        if "create" in cmd:
+            raise subprocess.CalledProcessError(
+                returncode=1,
+                cmd=cmd,
+                stderr=f'ERROR: existing instance for "{DockerImageBuilder._builder_name}" already exists',
+            )
+        return result
+
+    with patch(
+        "flyte._internal.imagebuild.docker_builder.run_sync_with_loop", side_effect=lambda fn, *a, **kw: fn(*a, **kw)
+    ):
+        with patch("subprocess.run", side_effect=mock_run):
+            # Should not raise.
+            await DockerImageBuilder._ensure_buildx_builder()
+
+
+@pytest.mark.asyncio
+async def test_ensure_buildx_builder_wraps_ls_failure_as_image_build_error():
+    """When `docker buildx ls` fails, surface an actionable ImageBuildError instead of a crash."""
+    from flyte.errors import ImageBuildError
+
+    def mock_run(cmd, **kwargs):
+        if cmd == ["docker", "buildx", "ls"]:
+            raise subprocess.CalledProcessError(returncode=1, cmd=cmd, stderr="Cannot connect to the Docker daemon")
+        return subprocess.CompletedProcess(cmd, 0)
+
+    with patch(
+        "flyte._internal.imagebuild.docker_builder.run_sync_with_loop", side_effect=lambda fn, *a, **kw: fn(*a, **kw)
+    ):
+        with patch("subprocess.run", side_effect=mock_run):
+            with pytest.raises(ImageBuildError, match="Failed to list docker buildx builders"):
+                await DockerImageBuilder._ensure_buildx_builder()
+
+
 @pytest.mark.asyncio
 async def test_build_image_uses_custom_builder_from_env(monkeypatch):
     """When FLYTE_DOCKER_BUILDKIT_BUILDER_NAME is set, _build_image should use it and skip _ensure_buildx_builder."""