fix: clear error for missing .dockerignore in with_dockerignore

A non-existent path passed to Image.with_dockerignore() surfaced as a raw
FileNotFoundError at build time (often because a relative path like
'.dockerignore' was resolved against the builder's working directory rather
than where the image was defined).

Resolve the path to an absolute path at definition time and raise a clear
ImageBuildError (a RuntimeUserError) when the file is missing, in both the
remote and local docker build paths.

fixes FLYTE-SDK-4Z

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

Author: EngHabu

src/flyte/_image.py

@@ -1180,7 +1180,17 @@ def with_code_bundle(
         return self.clone(addl_layer=CodeBundleLayer(copy_style=copy_style, dst=dst))
 
     def with_dockerignore(self, path: Path) -> Image:
-        new_image = self.clone(addl_layer=DockerIgnore(path=str(path)))
+        import flyte.errors
+
+        # Resolve to an absolute path so the file can still be located at build time, which may run
+        # from a different working directory than where the image was defined (e.g. the remote builder).
+        resolved = Path(path).expanduser()
+        if not resolved.is_file():
+            raise flyte.errors.ImageBuildError(
+                f"The .dockerignore file specified via with_dockerignore() was not found at '{path}'. "
+                f"Ensure the path points to an existing file."
+            )
+        new_image = self.clone(addl_layer=DockerIgnore(path=str(resolved.resolve())))
         return new_image
 
     def with_uv_project(

src/flyte/_internal/imagebuild/docker_builder.py

@@ -393,6 +393,13 @@ async def handle(
 class DockerIgnoreHandler:
     @staticmethod
     async def handle(layer: DockerIgnore, context_path: Path, _: str):
+        if not Path(layer.path).is_file():
+            from flyte.errors import ImageBuildError
+
+            raise ImageBuildError(
+                f"The .dockerignore file specified via with_dockerignore() was not found at '{layer.path}'. "
+                f"Ensure the path points to an existing file."
+            )
         shutil.copy(layer.path, context_path)
 
 

src/flyte/_internal/imagebuild/remote_builder.py

@@ -402,6 +402,11 @@ def _get_layers_proto(image: Image, context_path: Path) -> "image_definition_pb2
             )
             layers.append(commands_layer)
         elif isinstance(layer, DockerIgnore):
+            if not Path(layer.path).is_file():
+                raise flyte.errors.ImageBuildError(
+                    f"The .dockerignore file specified via with_dockerignore() was not found at '{layer.path}'. "
+                    f"Ensure the path points to an existing file."
+                )
             shutil.copy(layer.path, context_path)
         elif isinstance(layer, CodeBundleLayer):
             if layer.root_dir is None:

tests/flyte/test_image.py

@@ -601,6 +601,31 @@ def test_image_uri_changes_when_dockerignore_content_changes(tmp_path):
     assert uri1 != img2.uri
 
 
+def test_with_dockerignore_missing_file_raises_image_build_error(tmp_path):
+    """A non-existent .dockerignore path must raise a clear ImageBuildError, not a raw FileNotFoundError."""
+    from flyte.errors import ImageBuildError
+
+    missing = tmp_path / ".dockerignore"  # never created
+    with pytest.raises(ImageBuildError, match="with_dockerignore"):
+        Image.from_debian_base(registry="localhost", name="test").with_dockerignore(missing)
+
+
+def test_with_dockerignore_resolves_to_absolute_path(tmp_path, monkeypatch):
+    """with_dockerignore must store an absolute path so the file is locatable from any cwd at build time."""
+    from flyte._image import DockerIgnore
+
+    di_file = tmp_path / ".dockerignore"
+    di_file.write_text("*.log\n")
+
+    # Reference the file via a relative path from tmp_path, then change cwd to simulate the builder.
+    monkeypatch.chdir(tmp_path)
+    img = Image.from_debian_base(registry="localhost", name="test").with_dockerignore(Path(".dockerignore"))
+
+    layer = next(layer for layer in img._layers if isinstance(layer, DockerIgnore))
+    assert Path(layer.path).is_absolute()
+    assert Path(layer.path).is_file()
+
+
 def test_ids_for_different_python_version():
     ex_11 = Image.from_debian_base(python_version=(3, 11), install_flyte=False).with_source_file(Path(__file__))
     ex_12 = Image.from_debian_base(python_version=(3, 12), install_flyte=False).with_source_file(Path(__file__))