filtering is not supported when specifying a list of…

Error message

filtering is not supported when specifying a list of containers

What it means

Returned by the stats command when the user passes both an explicit list of container names/IDs and a --filter. The two code paths are mutually exclusive: a container list takes stats directly per container, while filters query the container list API. The guard at stats.go:243-245 rejects the combination in the list branch.

Solutions

Use EITHER explicit container IDs/names OR --filter, not both.
If you need selection, use --filter alone: `docker stats --filter name=web`.
If you already know the IDs, pass them positionally and drop --filter.

Example fix

// before
docker stats --filter name=web c1 c2

// after
docker stats c1 c2

Defensive patterns

Strategy: validation

Validate before calling

func validateStats(containers []string, filters map[string]string) error {
    if len(containers) > 0 && len(filters) > 0 {
        return errors.New("filtering is not supported when specifying a list of containers")
    }
    return nil
}

Prevention

Pick one selection mechanism per stats call: explicit IDs or filters.
If IDs are dynamic, derive them via `docker ps -q --filter ...` first, then pass the IDs.

When it happens

Trigger: `docker stats --filter name=web c1 c2` — both positional containers and a filter. options.Containers is non-empty and options.Filters is non-empty.

Common situations: Combining a filter habit (`--filter name=...`) with explicit IDs in scripts. Copy-pasting filter usage into a command that already names containers. Templating that emits both unconditionally.

Related errors

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

Appendix: 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 4f84911bfe)