{"record":{"id":"38309d0683be8351","repo":"docker/cli","slug":"specify-only-one-h","errorCode":null,"errorMessage":"specify only one -H","messagePattern":"specify only one -H","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/cli.go","lineNumber":593,"sourceCode":"\tops = append(defaultOps, ops...)\n\n\tcli := &DockerCli{baseCtx: context.Background()}\n\tfor _, op := range ops {\n\t\tif err := op(cli); err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t}\n\treturn cli, nil\n}\n\nfunc getServerHost(hosts []string, defaultToTLS bool) (string, error) {\n\tswitch len(hosts) {\n\tcase 0:\n\t\treturn dopts.ParseHost(defaultToTLS, os.Getenv(client.EnvOverrideHost))\n\tcase 1:\n\t\treturn dopts.ParseHost(defaultToTLS, hosts[0])\n\tdefault:\n\t\treturn \"\", errors.New(\"specify only one -H\")\n\t}\n}\n\n// UserAgent returns the default user agent string used for making API requests.\nfunc UserAgent() string {\n\treturn \"Docker-Client/\" + version.Version + \" (\" + runtime.GOOS + \")\"\n}\n\nvar defaultStoreEndpoints = []store.NamedTypeGetter{\n\tstore.EndpointTypeGetter(docker.DockerEndpoint, func() any { return &docker.EndpointMeta{} }),\n}\n\n// RegisterDefaultStoreEndpoints registers a new named endpoint\n// metadata type with the default context store config, so that\n// endpoint will be supported by stores using the config returned by\n// DefaultContextStoreConfig.\nfunc RegisterDefaultStoreEndpoints(ep ...store.NamedTypeGetter) {\n\tdefaultStoreEndpoints = append(defaultStoreEndpoints, ep...)","sourceCodeStart":575,"sourceCodeEnd":611,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/cli.go#L575-L611","documentation":"getServerHost (cli/command/cli.go:586) switches on len(hosts). When more than one --host/-H value is present (default case at line 593) it returns errors.New(\"specify only one -H\"). The CLI's Hosts slice accepts multiple -H flags but the daemon endpoint must resolve to a single host, so >1 is rejected.","triggerScenarios":"Running `docker -H host1 -H host2 ps`, or any invocation where opts.Hosts has length >= 2 (e.g. a flag parser or wrapper appending -H repeatedly). The first two cases (0 → use DOCKER_HOST env; 1 → use it) are valid.","commonSituations":"Shell aliases that append -H (e.g. `alias docker='docker -H $A -H $B'`); compose/wrapper scripts concatenating host lists; COPY-paste of commands accumulating -H flags.","solutions":["Provide at most one -H/--host flag on the command line.","If you need different hosts, run separate commands per host rather than multiple -H.","For multiple endpoints, use named contexts (`docker context create`) and switch via --context instead of multiple -H.","Inspect your alias/function for accidental duplicate -H."],"exampleFix":"# before\ndocker -H tcp://a:2376 -H tcp://b:2376 ps\n# after\ndocker -H tcp://a:2376 ps","handlingStrategy":"validation","validationCode":"// Enforce at most one -H before reaching getServerHost:\nif len(hosts) > 1 {\n    return errors.New(\"specify only one -H\")\n}\n// or: hosts = hosts[:1] // take the first if that is the intended behavior","typeGuard":null,"tryCatchPattern":"host, err := getServerHost(hosts, tls)\nif err != nil && strings.Contains(err.Error(), \"specify only one -H\") {\n    // prompt user / take hosts[0] / abort with guidance\n}","preventionTips":["Use a single -H/--host per command.","Prefer named contexts for multiple endpoints.","Audit aliases that append -H.","Validate len(hosts) <= 1 in your wrapper before invoking the CLI."],"tags":["cli","host","configuration"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}