{"record":{"id":"2c56bcb36399ea32","repo":"docker/cli","slug":"filtering-is-not-supported-when-specifying-a-list","errorCode":null,"errorMessage":"filtering is not supported when specifying a list of containers","messagePattern":"filtering is not supported when specifying a list of containers","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/container/stats.go","lineNumber":244,"sourceCode":"\t\tfor _, ctr := range cs.Items {\n\t\t\tif s := NewStats(ctr.ID); cStats.add(s) {\n\t\t\t\twaitFirst.Add(1)\n\t\t\t\tlog.G(ctx).WithFields(log.Fields{\n\t\t\t\t\t\"container\": ctr.ID,\n\t\t\t\t}).Debug(\"collecting stats for container\")\n\t\t\t\tgo collect(ctx, s, apiClient, !options.NoStream, waitFirst)\n\t\t\t}\n\t\t}\n\n\t\t// make sure each container get at least one valid stat data\n\t\twaitFirst.Wait()\n\t} else {\n\t\t// TODO(thaJeztah): re-implement options.Containers as a filter so that\n\t\t// only a single code-path is needed, and custom filters can be combined\n\t\t// with a list of container names/IDs.\n\n\t\tif len(options.Filters) > 0 {\n\t\t\treturn errors.New(\"filtering is not supported when specifying a list of containers\")\n\t\t}\n\n\t\t// Create the list of containers, and start collecting stats for all\n\t\t// containers passed.\n\t\tfor _, ctr := range options.Containers {\n\t\t\tif s := NewStats(ctr); cStats.add(s) {\n\t\t\t\twaitFirst.Add(1)\n\t\t\t\tlog.G(ctx).WithFields(log.Fields{\n\t\t\t\t\t\"container\": ctr,\n\t\t\t\t}).Debug(\"collecting stats for container\")\n\t\t\t\tgo collect(ctx, s, apiClient, !options.NoStream, waitFirst)\n\t\t\t}\n\t\t}\n\n\t\t// We don't expect any asynchronous errors: closeChan can be closed and disabled.\n\t\tclose(closeChan)\n\t\tcloseChan = nil\n","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/container/stats.go#L226-L262","documentation":"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.","triggerScenarios":"`docker stats --filter name=web c1 c2` — both positional containers and a filter. options.Containers is non-empty and options.Filters is non-empty.","commonSituations":"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.","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."],"exampleFix":"// before\ndocker stats --filter name=web c1 c2\n\n// after\ndocker stats c1 c2","handlingStrategy":"validation","validationCode":"func validateStats(containers []string, filters map[string]string) error {\n    if len(containers) > 0 && len(filters) > 0 {\n        return errors.New(\"filtering is not supported when specifying a list of containers\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["stats","cli-options","filter","container","conflicting-flags"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}