docker/cli · info · cancelledErr

containers prune has been cancelled

Error message

containers prune has been cancelled

What it means

Returned by pruneFn (the container pruner plugged into 'docker system prune') when options.Confirmed is false. This is the dry-run path: pruneFn emits a confirmation message and a cancelledErr so the system-prune aggregator knows pruning was not actually executed. It is structurally identical to the standalone prune cancellation but flows through the system pruner.

Solutions

1. Pass Confirmed=true (or use `docker system prune -f`) to actually prune.
2. Detect the Cancelled() interface on the returned error to distinguish abort from real failure.
3. Treat the returned confirmation message as the dry-run output rather than an error in callers.

Example fix

// before
docker system prune   # user declined

// after
docker system prune -f

// For programmatic use, set Confirmed=true to actually prune.
options.Confirmed = true

// cancelledErr implements Cancelled(); detect via interface assertion.
func isCancelled(err error) bool {
    var c interface{ Cancelled() }
    return errors.As(err, &c)
}

space, out, err := pruneFn(ctx, cli, pruneOpts)
if err != nil {
    var c interface{ Cancelled() }
    if errors.As(err, &c) {
        // dry-run / declined — `out` holds the confirmation message
        log.Println("dry-run:", out)
        return nil
    }
    return err
}

When it happens

Trigger: Running `docker system prune` without --force and declining confirmation, or invoking pruneFn programmatically with Confirmed=false. The dry-run branch at prune.go:104-108 returns this.

Common situations: System prune in interactive mode where the user aborts. Custom orchestration calling the pruner with Confirmed=false to preview what would be removed.

Related errors

• container prune has been cancelled
• builder prune has been cancelled
• image prune has been cancelled
• network prune has been cancelled
• system prune has been cancelled

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/f4193f26cb033b3c. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/container/prune.go:107

			out.WriteString(id + "\n")
		}
		spaceReclaimed = res.Report.SpaceReclaimed
	}

	return spaceReclaimed, out.String(), nil
}

type cancelledErr struct{ error }

func (cancelledErr) Cancelled() {}

// pruneFn calls the Container Prune API for use in "docker system prune",
// and returns the amount of space reclaimed and a detailed output string.
func pruneFn(ctx context.Context, dockerCLI command.Cli, options pruner.PruneOptions) (uint64, string, error) {
	if !options.Confirmed {
		// Dry-run: perform validation and produce confirmation before pruning.
		confirmMsg := "all stopped containers"
		return 0, confirmMsg, cancelledErr{errors.New("containers prune has been cancelled")}
	}
	return runPrune(ctx, dockerCLI, pruneOptions{
		force:  true,
		filter: options.Filter,
	})
}

View on GitHub (pinned to 4f84911bfe)