What causes "arguments to --filter should be in form KEY=VAL" in docker/compose?

Rewrite the filter as KEY=VAL, e.g. `--filter status=running`.

arguments to --filter should be in form KEY=VAL

Error message

arguments to --filter should be in form KEY=VAL

What it means

docker compose ps --filter accepts a single KEY=VAL string. parseFilter in cmd/compose/ps.go uses strings.Cut on '='; if no '=' separates key and value, the error is returned before any key-specific handling. Valid keys are 'status' (value appended to Status list) and 'source' (currently api.ErrNotImplemented); any other key yields 'unknown filter <key>'.

Source

Thrown at cmd/compose/ps.go:55

type psOptions struct {
	*ProjectOptions
	Format   string
	All      bool
	Quiet    bool
	Services bool
	Filter   string
	Status   []string
	noTrunc  bool
	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...]",

View on GitHub (pinned to ddc4b044b6)

Solutions

Rewrite the filter as KEY=VAL, e.g. `--filter status=running`.
Verify the key is one of the supported ones: status (or source, which is not yet implemented).
For multiple statuses, repeat the flag: `--filter status=running --filter status=paused`.

Example fix

# before
docker compose ps --filter running

# after
docker compose ps --filter status=running

Defensive patterns

Strategy: validation

Validate before calling

# compose ps filter must be KEY=VAL with key in {status,source}
case "$FILTER" in
  status=*|source=*) docker compose ps --filter "$FILTER" ;;
  *) echo "filter must be status=VAL or source=VAL (KEY=VAL form)" >&2; exit 1 ;;
esac

Prevention

Always write ps filters in KEY=VAL form; validate with a case pattern before running.
Remember only one --filter string is parsed by ps (unlike docker ps).

When it happens

Trigger: `docker compose ps --filter running`, `--filter status` (missing =VAL), or `--filter paused` (missing value). Note the ps filter flag is a plain string, so only one --filter is honored and it must contain '='.

Common situations: Carrying over docker ps habits (`docker ps --filter status=running` works, but omitting the '=' form is common in hastily written scripts); shell variables that expand to a bare word without the =VAL part.

Related errors

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