What causes "unknown filter %s" in docker/compose?

Use `--filter status= ` which is the only implemented filter key.

unknown filter %s

Error message

unknown filter %s

What it means

`docker compose ps --filter` currently supports only `status=<value>`; `source=` is explicitly not implemented (returns api.ErrNotImplemented) and every other key falls through to this 'unknown filter' error in parseFilter.

Source

Thrown at cmd/compose/ps.go:64

	Orphans  bool
}

func (p *psOptions) parseFilter() error {
	if p.Filter == "" {
		return nil
	}
	key, val, ok := strings.Cut(p.Filter, "=")
	if !ok {
		return errors.New("arguments to --filter should be in form KEY=VAL")
	}
	switch key {
	case "status":
		p.Status = append(p.Status, val)
		return nil
	case "source":
		return api.ErrNotImplemented
	default:
		return fmt.Errorf("unknown filter %s", key)
	}
}

func psCommand(p *ProjectOptions, dockerCli command.Cli, backendOptions *BackendOptions) *cobra.Command {
	opts := psOptions{
		ProjectOptions: p,
	}
	psCmd := &cobra.Command{
		Use:   "ps [OPTIONS] [SERVICE...]",
		Short: "List containers",
		PreRunE: func(cmd *cobra.Command, args []string) error {
			return opts.parseFilter()
		},
		RunE: Adapt(func(ctx context.Context, args []string) error {
			return runPs(ctx, dockerCli, backendOptions, args, opts)
		}),
		ValidArgsFunction: completeServiceNames(dockerCli, p),
	}

View on GitHub (pinned to ddc4b044b6)

Solutions

Use `--filter status=<running|exited|...>` which is the only implemented filter key.
Filter by service instead: pass service names as positional args `docker compose ps web`.
For richer filtering, post-process `docker compose ps --format json` with jq.

Example fix

# before
docker compose ps --filter name=web

# after
docker compose ps --filter status=running web

Defensive patterns

Strategy: validation

Validate before calling

# bash: only allow the implemented filter key
FILTER_KEY="${FILTER%%=*}"
[ "$FILTER_KEY" = status ] || { echo "only --filter status=... is supported" >&2; exit 2; }
docker compose ps --filter "$FILTER"

Prevention

Don't port docker ps filters blindly; compose ps supports status only.
Use `--format json` + jq for name/label filtering.

When it happens

Trigger: Running `docker compose ps --filter name=web`, `--filter label=foo=bar`, or `--filter source=build` — anything whose KEY is not exactly `status`.

Common situations: Porting `docker ps --filter` invocations to compose; scripts assuming docker ps filter semantics (name, label, ancestor, etc.) carry over; hitting `source=` which exists in some docs but is not implemented yet in this version.

Related errors

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