What causes "unable to resolve docker endpoint: %w" in docker/cli?

Run docker context ls to confirm the active context exists and is valid; docker context use default to fall back to the default endpoint.

docker/cli · error

unable to resolve docker endpoint

Error message

unable to resolve docker endpoint: %w

What it means

Returned by NewAPIClientFromFlags() when resolveDockerEndpoint() fails to turn the selected docker context (or default endpoint) into a usable docker.Endpoint. resolveDockerEndpoint performs three steps against the context store: GetMetadata(contextName), EndpointFromContext(meta), and WithTLSData(...); failure at any step (missing context, corrupt metadata, or missing/inconsistent TLS material) is wrapped with this message at cli.go:298.

Solutions

Run docker context ls to confirm the active context exists and is valid; docker context use default to fall back to the default endpoint.
Recreate the broken context with docker context create after fixing TLS material, or remove it with docker context rm <name>.
Inspect the context metadata under ~/.docker/contexts/meta and the referenced TLS files; restore any missing ca.pem/cert.pem/key.pem with correct permissions.
If a custom DOCKER_HOST is intended, unset DOCKER_CONTEXT and use --host/-H instead to bypass context resolution.

Example fix

// before
DOCKER_CONTEXT=staging docker ps   # staging context has stale TLS paths
// after
docker context rm staging && docker context create staging --docker host=ssh://user@staging-host
docker context use staging

Defensive patterns

Strategy: validation

Validate before calling

// Validate the active context exists before building a client.
func validateDockerContext(ctxStore *command.ContextStoreWithDefault, name string) error {
    if _, err := ctxStore.GetMetadata(name); err != nil {
        return fmt.Errorf("context %q is not resolvable: %w", name, err)
    }
    return nil
}

Try / catch

client, err := command.NewAPIClientFromFlags(opts, cfg)
if err != nil {
    // surface a hint: 'docker context ls' / 'docker context use default' / check TLS files
}

Prevention

Pin DOCKER_CONTEXT to a context that is created as part of environment provisioning.
Version-control or script context creation so TLS paths always resolve.
Run docker context ls in CI smoke checks before the real command.

When it happens

Trigger: Constructing the API client from CLI flags when the resolved context name does not exist in the store, has corrupt/unexpected metadata, or its TLS endpoints reference ca/cert/key files that cannot be read or are inconsistent. This path runs for every CLI invocation that builds a client through NewAPIClientFromFlags (the standard entry point).

Common situations: A docker context created on another machine referencing TLS files not present here; a context whose metadata got partially rewritten/edited by hand; switching DOCKER_CONTEXT to a name that was deleted; corrupted context store under ~/.docker/contexts/meta; TLS cert/key path permission issues.

Related errors

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

Appendix: source

Thrown at cli/command/cli.go:298

	return nil
}

// NewAPIClientFromFlags creates a new APIClient from command line flags
func NewAPIClientFromFlags(opts *cliflags.ClientOptions, configFile *configfile.ConfigFile) (client.APIClient, error) {
	if opts.Context != "" && len(opts.Hosts) > 0 {
		return nil, errors.New("conflicting options: cannot specify both --host and --context")
	}

	storeConfig := DefaultContextStoreConfig()
	contextStore := &ContextStoreWithDefault{
		Store: store.New(config.ContextStoreDir(), storeConfig),
		Resolver: func() (*DefaultContext, error) {
			return resolveDefaultContext(opts, storeConfig)
		},
	}
	endpoint, err := resolveDockerEndpoint(contextStore, resolveContextName(opts, configFile))
	if err != nil {
		return nil, fmt.Errorf("unable to resolve docker endpoint: %w", err)
	}
	return newAPIClientFromEndpoint(endpoint, configFile, client.WithUserAgent(UserAgent()))
}

func newAPIClientFromEndpoint(ep docker.Endpoint, configFile *configfile.ConfigFile, extraOpts ...client.Opt) (client.APIClient, error) {
	opts, err := ep.ClientOpts()
	if err != nil {
		return nil, err
	}
	if len(configFile.HTTPHeaders) > 0 {
		opts = append(opts, client.WithHTTPHeaders(configFile.HTTPHeaders))
	}
	withCustomHeaders, err := withCustomHeadersFromEnv()
	if err != nil {
		return nil, err
	}
	if withCustomHeaders != nil {
		opts = append(opts, withCustomHeaders)

View on GitHub (pinned to 4f84911bfe)