{"record":{"id":"232fcff43eb5c47e","repo":"docker/cli","slug":"specify-only-one-h-232fcf","errorCode":null,"errorMessage":"specify only one -H","messagePattern":"specify only one -H","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/flags/options.go","lineNumber":81,"sourceCode":"// slice. It produces an error when trying to set multiple values, matching\n// the check in [getServerHost].\n//\n// [getServerHost]: https://github.com/docker/cli/blob/7eab668982645def1cd46fe1b60894cba6fd17a4/cli/command/cli.go#L542-L551\ntype hostVar struct {\n\tdst *[]string\n\tset bool\n}\n\nfunc (h *hostVar) String() string {\n\tif h.dst == nil || len(*h.dst) == 0 {\n\t\treturn \"\"\n\t}\n\treturn (*h.dst)[0]\n}\n\nfunc (h *hostVar) Set(s string) error {\n\tif h.set {\n\t\treturn errors.New(\"specify only one -H\")\n\t}\n\t*h.dst = []string{s}\n\th.set = true\n\treturn nil\n}\n\nfunc (*hostVar) Type() string { return \"string\" }\n\n// ClientOptions are the options used to configure the client cli.\ntype ClientOptions struct {\n\tDebug      bool\n\tHosts      []string\n\tLogLevel   string\n\tTLS        bool\n\tTLSVerify  bool\n\tTLSOptions *tlsconfig.Options\n\tContext    string\n\tConfigDir  string","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/flags/options.go#L63-L99","documentation":"Returned by hostVar.Set (the custom flag value type for --host/-H) when the flag is specified a second time. Although the underlying ClientOptions.Hosts field is a slice for historical reasons, the CLI only allows connecting to a single daemon endpoint, so any repeat -H is rejected at parse time.","triggerScenarios":"Invoking a docker CLI command with two or more -H/--host flags, e.g. 'docker -H tcp://host1 -H tcp://host2 ps'. The second call to hostVar.Set sees h.set == true and errors.","commonSituations":"Scripts or aliases that prepend a default -H colliding with an explicit one; copy-pasting a command that already includes -H; migrating from a config that expected multiple hosts.","solutions":["Specify only a single -H/--host flag per invocation.","Use a Docker context (docker context use) instead of repeating -H across every command.","Set DOCKER_HOST once in the environment or shell profile rather than passing -H on the command line."],"exampleFix":"# before: docker -H tcp://node1:2375 -H tcp://node2:2375 ps\n# after:  docker -H tcp://node1:2375 ps   # or: docker context use node1 && docker ps","handlingStrategy":"validation","validationCode":"// Before invoking the CLI, ensure at most one -H is present\nfunc validateHostFlags(args []string) error {\n\tcount := 0\n\tfor _, a := range args {\n\t\tif a == \"-H\" || a == \"--host\" || strings.HasPrefix(a, \"-H=\") || strings.HasPrefix(a, \"--host=\") {\n\t\t\tcount++\n\t\t}\n\t}\n\tif count > 1 { return errors.New(\"specify only one -H\") }\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use docker context use instead of repeating -H on every command.","Set DOCKER_HOST in the environment rather than passing -H repeatedly.","Audit shell aliases and wrapper scripts for accidental double -H."],"tags":["cli","flags","host","validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}