docker/cli · error

specify only one -H

Error message

specify only one -H

What it means

Raised by getServerHost in cli/command/cli.go when more than one Docker daemon host was supplied. The docker CLI can only connect to a single daemon per invocation, so when the accumulated hosts slice has length greater than one it refuses to guess which endpoint to use and fails fast.

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 e9452d6e78)

Solutions

1. Remove the duplicate -H/--host flag and keep exactly one daemon endpoint per docker invocation.
2. Check shell aliases, DOCKER_* wrapper scripts, and Makefiles for a hidden -H flag before adding your own (`type docker`, `alias`).
3. If you need to target multiple daemons, use docker contexts (`docker context use <name>`) or run separate invocations instead of stacking -H flags.

Example fix

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

When it happens

Trigger: Passing the -H/--host flag more than once on the docker command line (e.g. `docker -H tcp://a:2375 -H tcp://b:2375 ps`), or combining a -H flag with a hosts list injected programmatically via CLI options so that len(hosts) > 1 when getServerHost runs during DockerCli initialization.

Common situations: Shell aliases or wrapper scripts that already embed a -H flag while the user adds another one; CI pipelines that both export DOCKER_HOST and pass -H through a templated command (only duplicate flags trigger it — DOCKER_HOST alone is used just when no -H is given); copy-pasted commands intended for docker swarm-era multi-host tooling.

Related errors

• conflicting options: --no-pause and --pause cannot be used t
• cannot supply extra formatting options to the pretty templat
• --format is incompatible with human friendly format
• placement preference must be of the format "<strategy>=<arg>
• failed to parse hook template

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/38309d0683be8351.json. Report an issue: GitHub.