docker/cli · error

unable to create docker endpoint config

Error message

unable to create docker endpoint config: %w

What it means

Returned by runUpdate (update.go:78) when getDockerEndpointMetadataAndTLS fails during 'docker context update --docker ...'. This wraps any error from getDockerEndpoint (config key validation, 'from=' resolution, ClientOpts, or client.New), so the underlying cause is in the wrapped %w. It specifically signals that the new Docker endpoint configuration supplied to 'update' could not be built.

Solutions

1. Read the wrapped error in the output - it carries the specific cause (host, key, TLS, from=).
2. Validate each --docker key=value against the allowed set: from, host, ca, cert, key, skip-tls-verify.
3. Test the new endpoint by creating a throwaway context first: 'docker context create --docker ... test' then 'docker context update'.
4. Ensure any referenced TLS files exist and are readable before running update.

Example fix

# before
docker context update my-ctx --docker host=daemon:2376,tls=true
# after
docker context update my-ctx --docker host=tcp://daemon:2376,skip-tls-verify=true

// Pre-validate the --docker key/value map the way getDockerEndpoint does.
func validateDockerConfig(config map[string]string) error {
	allowed := map[string]struct{}{"from":{},"host":{},"ca":{},"cert":{},"key":{},"skip-tls-verify":{}}
	for k := range config {
		if _, ok := allowed[k]; !ok { return fmt.Errorf("unrecognized key: %s", k) }
	}
	return nil
}

if err := cli.ContextUpdate(...); err != nil {
	if strings.Contains(err.Error(), "unable to create docker endpoint config") {
		// the wrapped error has the real cause; surface it to the user for correction
	}
}

When it happens

Trigger: Running 'docker context update <name> --docker host=...' with an invalid host, an unknown config key, an invalid skip-tls-verify value, a broken 'from=' source, or invalid TLS material. Any of the getDockerEndpoint failure paths (errors 320-322) surface here when triggered via the update command.

Common situations: Updating a context to point at a new daemon but mistyping the host scheme; changing TLS settings and supplying a path that does not exist; adding an unrecognized --docker key (e.g., 'tls=true' instead of skip-tls-verify).

Related errors

• unable to get endpoint from context
• invalid docker endpoint options
• 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/2a0faaa4052fa81c. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/context/update.go:78

	if err != nil {
		return err
	}
	dockerContext, err := command.GetDockerContext(c)
	if err != nil {
		return err
	}
	if opts.description != "" {
		dockerContext.Description = opts.description
	}

	c.Metadata = dockerContext

	tlsDataToReset := make(map[string]*store.EndpointTLSData)

	if opts.endpoint != nil {
		dockerEP, dockerTLS, err := getDockerEndpointMetadataAndTLS(s, opts.endpoint)
		if err != nil {
			return fmt.Errorf("unable to create docker endpoint config: %w", err)
		}
		c.Endpoints[docker.DockerEndpoint] = dockerEP
		tlsDataToReset[docker.DockerEndpoint] = dockerTLS
	}
	if err := validateEndpoints(c); err != nil {
		return err
	}
	if err := s.CreateOrUpdate(c); err != nil {
		return err
	}
	for ep, tlsData := range tlsDataToReset {
		if err := s.ResetEndpointTLSMaterial(name, ep, tlsData); err != nil {
			return err
		}
	}

	_, _ = fmt.Fprintln(dockerCLI.Out(), name)
	_, _ = fmt.Fprintf(dockerCLI.Err(), "Successfully updated context %q\n", name)

View on GitHub (pinned to 4f84911bfe)