docker/cli · error

specify only one -H

Error message

specify only one -H

What it means

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.

Solutions

1. Specify only a single -H/--host flag per invocation.
2. Use a Docker context (docker context use) instead of repeating -H across every command.
3. Set DOCKER_HOST once in the environment or shell profile rather than passing -H on the command line.

Example fix

# before: docker -H tcp://node1:2375 -H tcp://node2:2375 ps
# after:  docker -H tcp://node1:2375 ps   # or: docker context use node1 && docker ps

// Before invoking the CLI, ensure at most one -H is present
func validateHostFlags(args []string) error {
	count := 0
	for _, a := range args {
		if a == "-H" || a == "--host" || strings.HasPrefix(a, "-H=") || strings.HasPrefix(a, "--host=") {
			count++
		}
	}
	if count > 1 { return errors.New("specify only one -H") }
	return nil
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• conflicting options: cannot specify both --host and…
• specify only one -H
• unrecognized config key
• tag can't be used with --all-tags/-a
• tag can't be used with --all-tags/-a

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/232fcff43eb5c47e. Report an issue: GitHub.

Appendix: source

Thrown at cli/flags/options.go:81

// slice. It produces an error when trying to set multiple values, matching
// the check in [getServerHost].
//
// [getServerHost]: https://github.com/docker/cli/blob/7eab668982645def1cd46fe1b60894cba6fd17a4/cli/command/cli.go#L542-L551
type hostVar struct {
	dst *[]string
	set bool
}

func (h *hostVar) String() string {
	if h.dst == nil || len(*h.dst) == 0 {
		return ""
	}
	return (*h.dst)[0]
}

func (h *hostVar) Set(s string) error {
	if h.set {
		return errors.New("specify only one -H")
	}
	*h.dst = []string{s}
	h.set = true
	return nil
}

func (*hostVar) Type() string { return "string" }

// ClientOptions are the options used to configure the client cli.
type ClientOptions struct {
	Debug      bool
	Hosts      []string
	LogLevel   string
	TLS        bool
	TLSVerify  bool
	TLSOptions *tlsconfig.Options
	Context    string
	ConfigDir  string

View on GitHub (pinned to 4f84911bfe)