docker/cli · error

specify only one -H

Error message

specify only one -H

What it means

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.

Solutions

1. Provide at most one -H/--host flag on the command line.
2. If you need different hosts, run separate commands per host rather than multiple -H.
3. For multiple endpoints, use named contexts (`docker context create`) and switch via --context instead of multiple -H.
4. Inspect your alias/function for accidental duplicate -H.

Example fix

# before
docker -H tcp://a:2376 -H tcp://b:2376 ps
# after
docker -H tcp://a:2376 ps

// Enforce at most one -H before reaching getServerHost:
if len(hosts) > 1 {
    return errors.New("specify only one -H")
}
// or: hosts = hosts[:1] // take the first if that is the intended behavior

host, err := getServerHost(hosts, tls)
if err != nil && strings.Contains(err.Error(), "specify only one -H") {
    // prompt user / take hosts[0] / abort with guidance
}

When it happens

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

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

Related errors

• conflicting options: cannot specify both --host and…
• specify only one -H
• bad format for add-host
• failed to parse hook template
• plugin SchemaVersion version cannot be empty

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

Appendix: source

Thrown at cli/command/cli.go:593

	ops = append(defaultOps, ops...)

	cli := &DockerCli{baseCtx: context.Background()}
	for _, op := range ops {
		if err := op(cli); err != nil {
			return nil, err
		}
	}
	return cli, nil
}

func getServerHost(hosts []string, defaultToTLS bool) (string, error) {
	switch len(hosts) {
	case 0:
		return dopts.ParseHost(defaultToTLS, os.Getenv(client.EnvOverrideHost))
	case 1:
		return dopts.ParseHost(defaultToTLS, hosts[0])
	default:
		return "", errors.New("specify only one -H")
	}
}

// UserAgent returns the default user agent string used for making API requests.
func UserAgent() string {
	return "Docker-Client/" + version.Version + " (" + runtime.GOOS + ")"
}

var defaultStoreEndpoints = []store.NamedTypeGetter{
	store.EndpointTypeGetter(docker.DockerEndpoint, func() any { return &docker.EndpointMeta{} }),
}

// RegisterDefaultStoreEndpoints registers a new named endpoint
// metadata type with the default context store config, so that
// endpoint will be supported by stores using the config returned by
// DefaultContextStoreConfig.
func RegisterDefaultStoreEndpoints(ep ...store.NamedTypeGetter) {
	defaultStoreEndpoints = append(defaultStoreEndpoints, ep...)

View on GitHub (pinned to 4f84911bfe)