conflicting options: cannot specify both --host and…

Error message

conflicting options: cannot specify both --host and --context

What it means

DockerCli.Initialize (cli/command/cli.go:211) validates that the --context and --host flags are not both supplied at line 226-227: if opts.Context is non-empty AND len(opts.Hosts) > 0, it returns errors.New("conflicting options: cannot specify both --host and --context"). These options specify the daemon endpoint in two mutually exclusive ways (a named context vs. an explicit host URL).

Solutions

Use ONLY --context (and `docker context use`) OR only --host/-H — never both.
Unset DOCKER_HOST (`unset DOCKER_HOST`) if you intend to use --context.
Check your shell alias/functions (`alias docker`) for a hardcoded --host.
Run `docker context ls` and `echo $DOCKER_HOST` to identify which is being supplied.

Example fix

# before
docker --context remote --host tcp://1.2.3.4:2376 ps
# after — pick one
docker --context remote ps
# or
docker --host tcp://1.2.3.4:2376 ps

Defensive patterns

Strategy: validation

Validate before calling

// Resolve a single endpoint source before constructing options:
if ctxName != "" && host != "" {
    return errors.New("refusing to set both --context and --host; pick one")
}
opts.Context, opts.Hosts = ctxName, hosts

Try / catch

if err := cli.Initialize(opts); err != nil {
    if strings.Contains(err.Error(), "conflicting options: cannot specify both --host and --context") {
        // guidance: clear one of the two and retry / report to user
    }
    return err
}

Prevention

Standardize on Docker contexts; avoid mixing --host and --context.
Unset DOCKER_HOST when using contexts.
Audit shell aliases/functions for hardcoded -H.
Document the chosen endpoint mechanism for your team.

When it happens

Trigger: Running `docker --context myctx --host tcp://1.2.3.4:2375 ...`, or setting both DOCKER_HOST env var and --context flag, or any combination where a non-empty --context coexists with one or more --host/-H values.

Common situations: Aliases/wrappers that always pass --host colliding with a user-specified --context; shell history editing; migrating from DOCKER_HOST to contexts without removing the old setting; scripts combining flags from different sources.

Related errors

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

Appendix: source

Thrown at cli/command/cli.go:227

// Initialize the dockerCli runs initialization that must happen after command
// line flags are parsed.
func (cli *DockerCli) Initialize(opts *cliflags.ClientOptions, ops ...CLIOption) error {
	for _, o := range ops {
		if err := o(cli); err != nil {
			return err
		}
	}
	cliflags.SetLogLevel(opts.LogLevel)

	if opts.ConfigDir != "" {
		config.SetDir(opts.ConfigDir)
	}

	if opts.Debug {
		debug.Enable()
	}
	if opts.Context != "" && len(opts.Hosts) > 0 {
		return errors.New("conflicting options: cannot specify both --host and --context")
	}

	if cli.contextStoreConfig == nil {
		// This path can be hit when calling Initialize on a DockerCli that's
		// not constructed through [NewDockerCli]. Using the default context
		// store without a config set will result in Endpoints from contexts
		// not being type-mapped correctly, and used as a generic "map[string]any",
		// instead of a [docker.EndpointMeta].
		//
		// When looking up the API endpoint (using [EndpointFromContext]), no
		// endpoint will be found, and a default, empty endpoint will be used
		// instead which in its turn, causes newAPIClientFromEndpoint to
		// be initialized with the default config instead of settings for
		// the current context (which may mean; connecting with the wrong
		// endpoint and/or TLS Config to be missing).
		//
		// [EndpointFromContext]: https://github.com/docker/cli/blob/33494921b80fd0b5a06acc3a34fa288de4bb2e6b/cli/context/docker/load.go#L139-L149
		if err := WithDefaultContextStoreConfig()(cli); err != nil {

View on GitHub (pinned to 4f84911bfe)