docker/cli · error

unable to apply docker endpoint options

Error message

unable to apply docker endpoint options: %w

What it means

Returned when client.New(opts...) fails while validating endpoint options in getDockerEndpoint. This is a secondary validation pass (noted by the FIXME at options.go:125) that actually instantiates a Docker client from the derived options to catch problems the earlier checks missed. Failure indicates the options, though syntactically valid, cannot form a working client.

Solutions

1. Verify TLS file integrity: ensure ca, cert, and key are valid PEM and that the cert matches the key (e.g., 'openssl x509 -in cert.pem -noout -modulus' vs 'openssl rsa -in key.pem -noout -modulus').
2. Drop the TLS flags and use skip-tls-verify=true as a diagnostic to isolate whether TLS material is the cause.
3. Re-create the context pointing at a known-good daemon host to confirm the options shape, then re-add TLS.
4. Upgrade the CLI to match the daemon/API version if this appeared after a version change.

Example fix

# before
docker context create --docker host=tcp://host:2376,ca=ca.pem,cert=cert.pem,key=wrong.key my-ctx
# after
docker context create --docker host=tcp://host:2376,ca=ca.pem,cert=cert.pem,key=key.pem my-ctx

// Verify TLS material pairs correctly before building the endpoint.
func validateTLSPair(ca, cert, key string) error {
	if cert == "" && key != "" || cert != "" && key == "" {
		return errors.New("cert and key must both be set or both empty")
	}
	// optionally: compare modulus of cert and key PEM blocks
	return nil
}

if err := cli.ContextCreate(...); err != nil {
	if strings.Contains(err.Error(), "unable to apply docker endpoint options") {
		// TLS material is likely inconsistent; re-check cert/key pairing
	}
}

When it happens

Trigger: Endpoint options pass ClientOpts() but client.New rejects them, e.g., because the resolved host is unreachable for option-validation reasons, custom HTTP headers/transport settings are invalid, or the TLS material is internally inconsistent (cert without matching key, expired CA). The client is created but not connected, so this is about option-construction, not network reachability.

Common situations: Supplying a cert file that does not pair with the given key; a CA path pointing to a directory rather than a file; version skew where client.New enforces checks the older context did not; corrupted TLS files that parse as empty.

Related errors

• failed to retrieve context tls info: ca.pem seems invalid
• no valid private key found
• archive format is invalid
• : parsing
• context does not exist

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

Appendix: source

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

	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)