Return nil if no local image of matching label found

Sources/Services/ContainerAPIService/Client/ClientImage.swift

@@ -185,7 +185,7 @@ extension ClientImage {
     public static func get(reference: String, containerSystemConfig: ContainerSystemConfig) async throws -> ClientImage {
         let all = try await self.list()
         guard let found = try self._search(reference: reference, in: all, containerSystemConfig: containerSystemConfig) else {
-            throw ContainerizationError(.notFound, message: "image with reference \(reference)")
+            throw ContainerizationError(.notFound, message: "image with reference \(reference) not found")
         }
         return found
     }
@@ -226,10 +226,6 @@ extension ClientImage {
             let withDefaultTag = r.description
 
             let localImageMatches = all.filter { $0.description.nameFromAnnotation() == withDefaultTag }
-            guard localImageMatches.count > 1 else {
-                return localImageMatches.first
-            }
-            // More than one image matched. Check against the tagged reference
             return localImageMatches.first { $0.reference == withDefaultTag }
         }()
         if let locallyBuiltImage {

Tests/IntegrationTests/Build/TestCLIBuilder.swift

@@ -1001,6 +1001,24 @@ struct TestCLIBuilder {
         }
     }
 
+    @Test func testImageRmAfterRetagFails() async throws {
+        try await ContainerFixture.with { f in
+            let dir = try f.createTempDir()
+            try f.createContext(dir: dir, dockerfile: "FROM scratch")
+            let image = "scratch:\(UUID().uuidString)"
+            let newImage = "scratch-new:\(UUID().uuidString)"
+
+            try f.build(tag: image, contextDir: dir)
+            try f.assertImageBuilt(image)
+
+            try f.doImageTag(image, newName: newImage)
+            try f.doRemoveImages([image])
+
+            let result = try f.run(["image", "rm", image])
+            #expect(result.status != 0, "expected removing an already-removed image to fail")
+        }
+    }
+
     /// Regression test: the context *root* itself (not an entry inside it) is a
     /// symlink to a sibling directory, e.g. `context -> real-context`. The build
     /// must resolve the symlink and use the real directory's contents.

docs/command-reference.md

@@ -653,7 +653,7 @@ No options.
 
 ### `container image delete (rm)`
 
-Deletes one or more images. If no images are provided, `--all` can be used to delete all images. Images currently referenced by running containers cannot be deleted without first removing those containers.
+Deletes one or more images. If no images are provided, `--all` can be used to delete all images. Images currently referenced by running containers cannot be deleted without first removing those containers. When multiple images match the given name, locally built image is deleted first.
 
 **Usage**