docker/cli · error

filtering is not supported when specifying a list of contain

Error message

filtering is not supported when specifying a list of containers

What it means

Raised in runStats for `docker stats` when explicit container names/IDs are passed together with --filter. The code has two separate paths — filter-driven discovery (with event subscription) and an explicit container list — and combining them is not yet implemented (a TODO in the source notes filters should eventually subsume the list), so the CLI rejects the combination.

Source

Thrown at cli/command/container/stats.go:244

		for _, ctr := range cs.Items {
			if s := NewStats(ctr.ID); cStats.add(s) {
				waitFirst.Add(1)
				log.G(ctx).WithFields(log.Fields{
					"container": ctr.ID,
				}).Debug("collecting stats for container")
				go collect(ctx, s, apiClient, !options.NoStream, waitFirst)
			}
		}

		// make sure each container get at least one valid stat data
		waitFirst.Wait()
	} else {
		// TODO(thaJeztah): re-implement options.Containers as a filter so that
		// only a single code-path is needed, and custom filters can be combined
		// with a list of container names/IDs.

		if len(options.Filters) > 0 {
			return errors.New("filtering is not supported when specifying a list of containers")
		}

		// Create the list of containers, and start collecting stats for all
		// containers passed.
		for _, ctr := range options.Containers {
			if s := NewStats(ctr); cStats.add(s) {
				waitFirst.Add(1)
				log.G(ctx).WithFields(log.Fields{
					"container": ctr,
				}).Debug("collecting stats for container")
				go collect(ctx, s, apiClient, !options.NoStream, waitFirst)
			}
		}

		// We don't expect any asynchronous errors: closeChan can be closed and disabled.
		close(closeChan)
		closeChan = nil

View on GitHub (pinned to e9452d6e78)

Solutions

1. Use only --filter and let docker stats discover matching containers: docker stats --filter label=app=web
2. Or use only the explicit container list: docker stats ctr1 ctr2
3. Pre-resolve the filter yourself: docker stats $(docker ps -q --filter label=app=web)

Example fix

# before
docker stats --filter label=app=web web1
# after
docker stats $(docker ps -q --filter label=app=web)

When it happens

Trigger: `docker stats --filter label=app=web ctr1` or any `docker stats [containers...]` invocation where options.Filters is non-empty and at least one container argument is given.

Common situations: Trying to narrow stats for a known container with a label/status filter; scripts that both compute a container list and pass a standing --filter flag; expecting --filter to behave like it does on docker ps where it composes with other selection.

Related errors

• conflicting options: cannot specify both --timeout and --tim
• conflicting options: cannot specify both --attach and --deta
• timeout waiting for stats
• conflicting options: cannot specify both --network-alias and
• valid streams are STDIN, STDOUT and STDERR

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/2c56bcb36399ea32.json. Report an issue: GitHub.