Rollback Partial Image Layers on Cancel vs. Abandon Operation: Which Should Portainer Choose?

Direct Answer

Portainer should not automatically delete partially pulled image layers when a user clicks Cancel. The risk of removing layers still referenced by other containers or images outweighs the disk-space benefit. Instead, Portainer should surface the orphaned layers in the UI and offer a safe, user-initiated cleanup action.

Why Automatic Rollback Is Unsafe

• Shared layer references: Docker images are content-addressable. A layer being pulled for image myapp:v2 may already be used by myapp:v1, base:latest, or any other image on the host. Deleting it because one pull was cancelled would corrupt those other images.
• Race with the watchdog: The current 30-second watchdog forces the HTTP connection closed if the daemon doesn't acknowledge the DELETE. If a rollback routine runs concurrently, it could attempt to remove layers while the daemon is still writing them, leaving the store in an inconsistent state.
• No transaction boundary: Docker's pull API does not expose a "transaction" that either fully commits or fully aborts. Layers are written incrementally; there is no atomic rollback point Portainer can invoke.

Safety Checks That Would Be Required (If You Still Wanted To Try)

If a future design insisted on automatic cleanup, every layer candidate for deletion would need to pass all of these checks:

1. Query docker image inspect --format '{{.RootFS.Layers}}' <image> for every image on the host to confirm the layer digest is not referenced anywhere.
2. Check docker ps -a --filter ancestor=<image> to ensure no stopped or running container uses the image.
3. Verify the layer is not referenced by any build cache entry (which may require parsing /var/lib/docker/buildkit or using the BuildKit API).
4. Serialize the cleanup behind a host-level lock so it cannot race with the watchdog's forced connection close.

These checks are expensive, fragile, and still cannot guarantee safety if a concurrent pull starts for the same layer.

Recommended Approach: Explicit, User-Driven Cleanup

1. Mark the task "cancelled" immediately in Portainer's task API (current behavior).
2. Record the image reference and layer digests that were in-flight at cancel time in the task metadata.
3. Expose a "Clean up cancelled pull" button in the task detail view. When clicked, run the safety checks above once and delete only layers that are truly unreferenced.
4. Add a periodic "Orphaned Layers" report in Settings → System → Disk Usage that aggregates layers from all cancelled/failed pulls and offers bulk removal after the same reference checks.

Interaction With the Existing Watchdog

Keep the 30-second watchdog unchanged. It only governs HTTP connection lifecycle, not disk state. The explicit cleanup runs minutes or hours later, completely outside the watchdog window, eliminating the race condition.

One Missing Diagnostic Detail

What is the typical median and p95 duration of a successful image pull in your target environments? If most pulls finish well under 30 seconds, the watchdog rarely fires and orphaned layers are rare — making the explicit cleanup UI a low-priority feature. If pulls routinely exceed 30 seconds (slow registries, large images), the watchdog fires often and the cleanup UI becomes high-value. Please provide those latency percentiles to prioritize the work.