docker/cli · error

placement preference must be of the format "<strategy>=<arg>

Error message

placement preference must be of the format "<strategy>=<arg>"

What it means

Raised by placementPrefOpts.Set, the pflag Value parser for --placement-pref on `docker service create/update`. The value must contain an '=' separating a non-empty strategy from its argument (strings.Cut must find '=' and yield a non-empty strategy). Currently only the "spread" strategy is supported; a well-formed but unknown strategy produces a different error.

Source

Thrown at cli/command/service/opts.go:101

type placementPrefOpts struct {
	prefs   []swarm.PlacementPreference
	strings []string
}

func (o *placementPrefOpts) String() string {
	if len(o.strings) == 0 {
		return ""
	}
	return fmt.Sprintf("%v", o.strings)
}

// Set validates the input value and adds it to the internal slices.
// Note: in the future strategies other than "spread", may be supported,
// as well as additional comma-separated options.
func (o *placementPrefOpts) Set(value string) error {
	strategy, arg, ok := strings.Cut(value, "=")
	if !ok || strategy == "" {
		return errors.New(`placement preference must be of the format "<strategy>=<arg>"`)
	}
	if strategy != "spread" {
		return fmt.Errorf("unsupported placement preference %s (only spread is supported)", strategy)
	}

	o.prefs = append(o.prefs, swarm.PlacementPreference{
		Spread: &swarm.SpreadOver{
			SpreadDescriptor: arg,
		},
	})
	o.strings = append(o.strings, value)
	return nil
}

// Type returns a string name for this Option type
func (*placementPrefOpts) Type() string {
	return "pref"
}

View on GitHub (pinned to e9452d6e78)

Solutions

1. Use the full form: `--placement-pref 'spread=node.labels.datacenter'`.
2. Ensure the node label referenced after `spread=` exists on your nodes (`docker node update --label-add datacenter=east <node>`).
3. Quote the value in shells/CI templates so the '=' survives expansion.

Example fix

# before
docker service create --placement-pref node.labels.dc nginx
# after
docker service create --placement-pref 'spread=node.labels.dc' nginx

When it happens

Trigger: `docker service create --placement-pref spread ...` (no '='), `--placement-pref '=node.labels.dc'` (empty strategy), or any value lacking the `<strategy>=<arg>` shape.

Common situations: Users passing just the label expression (`--placement-pref node.labels.datacenter`) and forgetting the `spread=` prefix, shell quoting stripping the '=', or templated commands where the strategy variable expands empty.

Related errors

• --format is incompatible with human friendly format
• invalid credential spec: value must be prefixed with "config
• error reading from STDIN: data is empty
• secret file is required
• got wrong object to inspect

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/338a1038e61c566c.json. Report an issue: GitHub.