{"id":"338a1038e61c566c","repo":"docker/cli","slug":"placement-preference-must-be-of-the-format-strat","errorCode":null,"errorMessage":"placement preference must be of the format \"<strategy>=<arg>\"","messagePattern":"placement preference must be of the format \"<strategy>=<arg>\"","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/service/opts.go","lineNumber":101,"sourceCode":"type placementPrefOpts struct {\n\tprefs   []swarm.PlacementPreference\n\tstrings []string\n}\n\nfunc (o *placementPrefOpts) String() string {\n\tif len(o.strings) == 0 {\n\t\treturn \"\"\n\t}\n\treturn fmt.Sprintf(\"%v\", o.strings)\n}\n\n// Set validates the input value and adds it to the internal slices.\n// Note: in the future strategies other than \"spread\", may be supported,\n// as well as additional comma-separated options.\nfunc (o *placementPrefOpts) Set(value string) error {\n\tstrategy, arg, ok := strings.Cut(value, \"=\")\n\tif !ok || strategy == \"\" {\n\t\treturn errors.New(`placement preference must be of the format \"<strategy>=<arg>\"`)\n\t}\n\tif strategy != \"spread\" {\n\t\treturn fmt.Errorf(\"unsupported placement preference %s (only spread is supported)\", strategy)\n\t}\n\n\to.prefs = append(o.prefs, swarm.PlacementPreference{\n\t\tSpread: &swarm.SpreadOver{\n\t\t\tSpreadDescriptor: arg,\n\t\t},\n\t})\n\to.strings = append(o.strings, value)\n\treturn nil\n}\n\n// Type returns a string name for this Option type\nfunc (*placementPrefOpts) Type() string {\n\treturn \"pref\"\n}","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/docker/cli/blob/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/service/opts.go#L83-L119","documentation":"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.","triggerScenarios":"`docker service create --placement-pref spread ...` (no '='), `--placement-pref '=node.labels.dc'` (empty strategy), or any value lacking the `<strategy>=<arg>` shape.","commonSituations":"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.","solutions":["Use the full form: `--placement-pref 'spread=node.labels.datacenter'`.","Ensure the node label referenced after `spread=` exists on your nodes (`docker node update --label-add datacenter=east <node>`).","Quote the value in shells/CI templates so the '=' survives expansion."],"exampleFix":"# before\ndocker service create --placement-pref node.labels.dc nginx\n# after\ndocker service create --placement-pref 'spread=node.labels.dc' nginx","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker-cli","swarm","services","placement","cli-flags","input-validation"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}