docker/cli · error

invalid docker endpoint options

Error message

invalid docker endpoint options: %w

What it means

Returned when docker.Endpoint.ClientOpts() fails during endpoint validation in getDockerEndpoint. ClientOpts() validates the assembled endpoint (host, TLS data, skip-tls-verify) and produces the client connection options; failure means the configuration is internally inconsistent or the host value is malformed/unparseable as a Docker daemon endpoint. The wrapping preserves the underlying cause via %w.

Solutions

1. Check the host value format: it must be a full URL like 'tcp://host:2376', 'unix:///var/run/docker.sock', or 'ssh://user@host'.
2. Remove the context and recreate it with a corrected --docker host= value.
3. If using TLS, ensure host uses a TLS-compatible scheme (tcp:// with port 2376) and that cert/key/ca paths are readable.
4. Run 'docker context inspect <name>' to see the stored host and compare against a known-good context.

Example fix

# before
docker context create --docker host=docker.example:2376 my-ctx
# after
docker context create --docker host=tcp://docker.example:2376 my-ctx

// Validate a host string is a parseable Docker endpoint before passing it
// as --docker host=.
import "github.com/moby/moby/client"

func validateHost(host string) error {
	opts, err := docker.Endpoint{EndpointMeta: docker.EndpointMeta{Host: host}}.ClientOpts()
	if err != nil { return err }
	_ = opts
	return nil
}

if err := cli.ContextCreate(...); err != nil {
	if strings.Contains(err.Error(), "invalid docker endpoint options") {
		// re-prompt for a corrected --docker host= value
	}
}

When it happens

Trigger: Creating/updating a context with '--docker host=<malformed-url>' where the host is not a valid Docker endpoint URL (e.g., missing scheme, unsupported scheme, empty host). Also triggered by contradictory TLS settings, such as providing TLS cert/key paths but an invalid or non-TLS host.

Common situations: Typo in the host value (e.g., 'host=docker:2376' missing the 'tcp://' scheme); pointing at a Unix socket with wrong formatting; copy-pasting a host from docs that uses a scheme this CLI version does not accept.

Related errors

• unable to get endpoint from context
• unable to create docker endpoint config
• failed to parse hook template
• plugin SchemaVersion version cannot be empty
• conflicting options: cannot specify both --host and…

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

Appendix: source

Thrown at cli/command/context/options.go:123

	tlsData, err := context.TLSDataFromFiles(config[keyCA], config[keyCert], config[keyKey])
	if err != nil {
		return docker.Endpoint{}, err
	}
	skipTLSVerify, err := parseBool(config, keySkipTLSVerify)
	if err != nil {
		return docker.Endpoint{}, err
	}
	ep := docker.Endpoint{
		EndpointMeta: docker.EndpointMeta{
			Host:          config[keyHost],
			SkipTLSVerify: skipTLSVerify,
		},
		TLSData: tlsData,
	}
	// try to resolve a docker client, validating the configuration
	opts, err := ep.ClientOpts()
	if err != nil {
		return docker.Endpoint{}, fmt.Errorf("invalid docker endpoint options: %w", err)
	}
	// FIXME(thaJeztah): this creates a new client (but discards it) only to validate the options; are the validation steps above not enough?
	if _, err := client.New(opts...); err != nil {
		return docker.Endpoint{}, fmt.Errorf("unable to apply docker endpoint options: %w", err)
	}
	return ep, nil
}

func getDockerEndpointMetadataAndTLS(contextStore store.Reader, config map[string]string) (docker.EndpointMeta, *store.EndpointTLSData, error) {
	ep, err := getDockerEndpoint(contextStore, config)
	if err != nil {
		return docker.EndpointMeta{}, nil, err
	}
	return ep.EndpointMeta, ep.TLSData.ToStoreTLSData(), nil
}

View on GitHub (pinned to 4f84911bfe)