docker/cli · error

ERROR: The "until" filter is not supported with "--volumes"

Error message

ERROR: The "until" filter is not supported with "--volumes"

What it means

Returned by pruneFn (volume/prune.go:126-128), the function registered for 'docker system prune --volumes'. The volume prune API does not support the 'until' time filter (unlike container/image prune), so the CLI pre-empts the daemon call and rejects it with this explicit message. The TODO at line 123 notes this check is client-side because daemon filter support may evolve.

Solutions

1. Remove the '--filter until=...' argument when pruning volumes.
2. For age-based volume cleanup, list volumes and delete selectively, or rely on --all/--filter label= instead.
3. Split the system prune so volumes are pruned separately without the until filter.

Example fix

# before
docker system prune --volumes --filter until=24h -f

# after
docker system prune --volumes -f

// Strip 'until' from filters when targeting volumes; the volume prune API does not support it.
func sanitizeVolumeFilters(filters map[string]string) (map[string]string, error) {
    if _, ok := filters["until"]; ok {
        return nil, errors.New(`the "until" filter is not supported when pruning volumes`)
    }
    return filters, nil
}

When it happens

Trigger: Running 'docker system prune --volumes --filter until=24h' (or any until= value). The check fires whenever the 'until' key is present in the resolved filter set passed to pruneFn.

Common situations: Reusing a prune filter recipe that works for 'docker container prune' or 'docker image prune' (which DO support until) against --volumes. Automation that applies a uniform 'until=' retention filter across all resource types.

Related errors

• conflicting options: cannot specify both --all and --filter…
• conflicting options: cannot specify a volume-name through…
• volume prune has been cancelled
• can only update cluster volumes
• bad format of filter (expected name=value)

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

Appendix: source

Thrown at cli/command/volume/prune.go:127

	return spaceReclaimed, out.String(), nil
}

type invalidParamErr struct{ error }

func (invalidParamErr) InvalidParameter() {}

type cancelledErr struct{ error }

func (cancelledErr) Cancelled() {}

// pruneFn calls the Volume 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) {
	// TODO version this once "until" filter is supported for volumes
	// Ideally, this check wasn't done on the CLI because the list of
	// filters that is supported by the daemon may evolve over time.
	if _, ok := options.Filter.Value()["until"]; ok {
		return 0, "", errors.New(`ERROR: The "until" filter is not supported with "--volumes"`)
	}
	if !options.Confirmed {
		// Dry-run: perform validation and produce confirmation before pruning.
		confirmMsg := "all anonymous volumes not used by at least one container"
		return 0, confirmMsg, cancelledErr{errors.New("volume prune has been cancelled")}
	}
	return runPrune(ctx, dockerCli, pruneOptions{
		force:  true,
		filter: options.Filter,
	})
}

View on GitHub (pinned to 4f84911bfe)