{"record":{"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":102,"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":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/service/opts.go#L84-L120","documentation":"The `--placement-pref` flag for `docker service create/update` expects values in the format `<strategy>=<argument>`. The `placementPrefOpts.Set` method at opts.go:99-103 uses `strings.Cut(value, \"=\")` to split the input. This error fires when there is no `=` separator at all (`ok == false`) or the strategy portion before `=` is empty. Currently only the \"spread\" strategy is supported (checked at line 104), but the format error is about the structural requirement, not the strategy choice.","triggerScenarios":"Passing `--placement-pref spread` (missing `=label`), `--placement-pref node.labels.zone` (missing strategy prefix entirely), or `--placement-pref =node.labels.zone` (empty strategy before `=`). Correct form: `--placement-pref spread=node.labels.zone`.","commonSituations":"A developer reads the help text and forgets the `=` separator, or mistakenly uses a space instead of `=`. Also common when copy-pasting placement constraint syntax (`node.labels.zone == us-east`) into placement-pref.","solutions":["Use the exact format: `--placement-pref spread=<label-descriptor>`, e.g., `--placement-pref spread=node.labels.zone`","Check that the strategy is \"spread\" (the only currently supported value) and that a non-empty label follows the `=`"],"exampleFix":"# before\ndocker service create --placement-pref \"spread\" --image nginx web\n# error: placement preference must be of the format \"<strategy>=<arg>\"\n\n# before (also wrong)\ndocker service create --placement-pref \"node.labels.zone\" --image nginx web\n\n# after\ndocker service create --placement-pref \"spread=node.labels.zone\" --image nginx web","handlingStrategy":"validation","validationCode":"// Validate placement preference before calling Set\nfunc validatePlacementPref(value string) error {\n    strategy, arg, ok := strings.Cut(value, \"=\")\n    if !ok || strategy == \"\" {\n        return fmt.Errorf(`placement preference must be of the format \"<strategy>=<arg>\"`)\n    }\n    if strategy != \"spread\" {\n        return fmt.Errorf(\"unsupported placement preference %s (only spread is supported)\", strategy)\n    }\n    if arg == \"\" {\n        return errors.New(\"placement preference argument cannot be empty\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always use the spread=<label> format — never omit the = separator","Validate placement preference strings in deployment scripts before passing to docker service create/update","Remember that only 'spread' is currently supported as a strategy"],"tags":["docker","cli","service","placement","swarm","flag-validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}