docker/cli · error

unable to create docker endpoint config

Error message

unable to create docker endpoint config: %w

What it means

Thrown by createNewContext when getDockerEndpointMetadataAndTLS fails while building the docker endpoint config from the --docker flag. The wrapped error describes the specific failure (bad host, unreadable TLS files, invalid client opts).

Solutions

1. Validate the host URL scheme: tcp://, unix://, npipe://, ssh://
2. Check TLS files exist and are readable: ls -l ca.pem cert.pem key.pem
3. Ensure cert and key are a matching pair
4. For non-TLS remote daemons, use --docker host=tcp://host:2375 or set skip-tls-verify=true

Example fix

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

// Validate endpoint config before creating a context.
for _, k := range []string{"ca", "cert", "key"} {
    if p, ok := endpoint[k]; ok && p != "" {
        if _, err := os.Stat(p); err != nil {
            return fmt.Errorf("%s file %q not readable: %w", k, p, err)
        }
    }
}
if u, err := url.Parse(endpoint["host"]); err != nil || u.Scheme == "" {
    return fmt.Errorf("bad host %q", endpoint["host"])
}

if err := runCreate(...); err != nil {
    if strings.Contains(err.Error(), "unable to create docker endpoint config") {
        // surface the wrapped cause to the user
    }
}

When it happens

Trigger: Running `docker context create NAME --docker host=...,ca=...,cert=...,key=...` with an invalid host URL, missing/unreadable TLS file paths, malformed endpoint options, or a client.New validation failure.

Common situations: Typo in host scheme (e.g. tcp:/ instead of tcp://); cert/key paths that don't exist; mismatched cert and key; unsupported host scheme; --from combined with --docker (rejected earlier) or skip-tls-verify with missing TLS material.

Related errors

• : parsing
• failed to remove TLS data for endpoint
• docker endpoint configuration is required
• cannot use --docker flag when --from is set
• default context cannot be edited

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

Appendix: source

Thrown at cli/command/context/create.go:92

	case opts.from != "":
		err = createFromExistingContext(s, name, opts.from, opts)
	default:
		err = createNewContext(s, name, opts)
	}
	if err == nil {
		_, _ = fmt.Fprintln(dockerCLI.Out(), name)
		_, _ = fmt.Fprintf(dockerCLI.Err(), "Successfully created context %q\n", name)
	}
	return err
}

func createNewContext(contextStore store.ReaderWriter, name string, opts createOptions) error {
	if opts.endpoint == nil {
		return errors.New("docker endpoint configuration is required")
	}
	dockerEP, dockerTLS, err := getDockerEndpointMetadataAndTLS(contextStore, opts.endpoint)
	if err != nil {
		return fmt.Errorf("unable to create docker endpoint config: %w", err)
	}
	contextMetadata := store.Metadata{
		Endpoints: map[string]any{
			docker.DockerEndpoint: dockerEP,
		},
		Metadata: command.DockerContext{
			Description:      opts.description,
			AdditionalFields: opts.metaData,
		},
		Name: name,
	}
	contextTLSData := store.ContextTLSData{}
	if dockerTLS != nil {
		contextTLSData.Endpoints = map[string]store.EndpointTLSData{
			docker.DockerEndpoint: *dockerTLS,
		}
	}
	if err := validateEndpoints(contextMetadata); err != nil {

View on GitHub (pinned to 4f84911bfe)