docker/cli · error

bad format of filter (expected name=value)

Error message

bad format of filter (expected name=value)

What it means

Returned by FilterOpt.Set (opts/opts.go:309) when a --filter value does not contain an '=' character. Filters must be specified as 'name=value'; the presence of '=' is checked before any splitting or normalization. An empty value ("") is allowed and returns nil (no-op), but a non-empty string without '=' is rejected.

Solutions

1. Format the filter as 'name=value', e.g., '--filter status=running' or '--filter label=color=blue'.
2. Consult 'docker <command> --help' for valid filter names for the specific command.

Example fix

// before: missing = in filter
// docker ps --filter running

// after: correct name=value format
// docker ps --filter status=running

func validateFilter(value string) error {
    if value == "" {
        return nil // empty is allowed (no-op)
    }
    if !strings.Contains(value, "=") {
        return fmt.Errorf("filter %q must be in name=value format", value)
    }
    return nil
}

if err := filterOpt.Set(value); err != nil {
    if err.Error() == "bad format of filter (expected name=value)" {
        return fmt.Errorf("filter %q is missing '='; use name=value format", value)
    }
    return err
}

When it happens

Trigger: A --filter flag receives a value with no '=' sign. For example: '--filter running' instead of '--filter status=running', or '--filter label.com.docker.compose.service' without '=value'.

Common situations: Typo or shorthand attempt (omitting the filter name), copy-paste from documentation that used abbreviated syntax, or misunderstanding that filters require a 'name=value' format.

Related errors

• conflicting options: cannot specify both --all and --filter…
• ERROR: The "until" filter is not supported with "--volumes"
• duration cannot be negative
• value is empty
• invalid field key

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

Appendix: source

Thrown at opts/opts.go:309

func (o *FilterOpt) String() string {
	if o == nil || len(o.filter) == 0 {
		return ""
	}
	repr, err := json.Marshal(o.filter)
	if err != nil {
		return "invalid filters"
	}
	return string(repr)
}

// Set sets the value of the opt by parsing the command line value
func (o *FilterOpt) Set(value string) error {
	if value == "" {
		return nil
	}
	if !strings.Contains(value, "=") {
		return errors.New("bad format of filter (expected name=value)")
	}
	name, val, _ := strings.Cut(value, "=")

	// TODO(thaJeztah): these options should not be case-insensitive.
	name = strings.ToLower(strings.TrimSpace(name))
	val = strings.TrimSpace(val)
	o.filter.Add(name, val)
	return nil
}

// Type returns the option type
func (*FilterOpt) Type() string {
	return "filter"
}

// Value returns the value of this option
func (o *FilterOpt) Value() client.Filters {
	return o.filter

View on GitHub (pinned to 4f84911bfe)