docker/compose · error

invalid filter '${filter}'

Error message

invalid filter '${filter}'

What it means

docker compose ls only supports a single filter key, "name" (defined in the acceptedListFilters map in cmd/compose/list.go). runList iterates over the parsed filter values and rejects any key not present in that map before contacting the backend. The error message interpolates the offending key, e.g. invalid filter 'status'.

Source

Thrown at cmd/compose/list.go:91

	fieldValues := filters[field]
	for name2match := range fieldValues {
		isMatch, err := regexp.MatchString(name2match, source)
		if err != nil {
			continue
		}
		if isMatch {
			return true
		}
	}
	return false
}

func runList(ctx context.Context, dockerCli command.Cli, backendOptions *BackendOptions, lsOpts lsOptions) error {
	filters := lsOpts.Filter.Value()

	for filter := range filters {
		if _, ok := acceptedListFilters[filter]; !ok {
			return errors.New("invalid filter '" + filter + "'")
		}
	}

	backend, err := compose.NewComposeService(dockerCli, backendOptions.Options...)
	if err != nil {
		return err
	}
	stackList, err := backend.List(ctx, api.ListOptions{All: lsOpts.All})
	if err != nil {
		return err
	}

	if len(filters) > 0 {
		var filtered []api.Stack
		for _, s := range stackList {
			if match(filters, "name", s.Name) {
				filtered = append(filtered, s)
			}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Use only the supported filter: `docker compose ls --filter name=<substring>`.
2. If you need to narrow by other attributes, filter client-side on the JSON output: `docker compose ls --format json | jq ...`.
3. Check for typos in the key name — the match is exact and case-sensitive.

Example fix

# before
docker compose ls --filter status=running

# after
docker compose ls --format json | jq '.[] | select(.State == "running")'

# only the 'name' key is accepted by docker compose ls --filter
validate_ls_filter() {
  case "$1" in
    name=*) return 0 ;;
    *) echo "unsupported ls filter: $1 (only name=VAL)" >&2; return 1 ;;
  esac
}
validate_ls_filter \"$FILTER\" && docker compose ls --filter \"$FILTER\"

When it happens

Trigger: Running `docker compose ls --filter status=running`, `--filter project=foo`, or any KEY=VAL whose KEY is not exactly 'name'; note the flag is a strings slice, so `--filter name=foo` works while anything else fails.

Common situations: Users assuming docker compose ls shares filter keys with docker compose ps (status) or docker CLI (label, id); copy-pasting ps filter syntax into ls commands in scripts or docs.

Related errors

• arguments to --filter should be in form KEY=VAL
• source can not be empty
• destination can not be empty
• --index requires one service to be selected
• cannot combine --attach and --attach-dependencies

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/609276ea0211f02a. Report an issue: GitHub.