{"record":{"id":"1b5b23256780fc40","repo":"docker/cli","slug":"unable-to-resolve-docker-endpoint-w","errorCode":null,"errorMessage":"unable to resolve docker endpoint: %w","messagePattern":"unable to resolve docker endpoint: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/cli.go","lineNumber":298,"sourceCode":"\treturn nil\n}\n\n// NewAPIClientFromFlags creates a new APIClient from command line flags\nfunc NewAPIClientFromFlags(opts *cliflags.ClientOptions, configFile *configfile.ConfigFile) (client.APIClient, error) {\n\tif opts.Context != \"\" && len(opts.Hosts) > 0 {\n\t\treturn nil, errors.New(\"conflicting options: cannot specify both --host and --context\")\n\t}\n\n\tstoreConfig := DefaultContextStoreConfig()\n\tcontextStore := &ContextStoreWithDefault{\n\t\tStore: store.New(config.ContextStoreDir(), storeConfig),\n\t\tResolver: func() (*DefaultContext, error) {\n\t\t\treturn resolveDefaultContext(opts, storeConfig)\n\t\t},\n\t}\n\tendpoint, err := resolveDockerEndpoint(contextStore, resolveContextName(opts, configFile))\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to resolve docker endpoint: %w\", err)\n\t}\n\treturn newAPIClientFromEndpoint(endpoint, configFile, client.WithUserAgent(UserAgent()))\n}\n\nfunc newAPIClientFromEndpoint(ep docker.Endpoint, configFile *configfile.ConfigFile, extraOpts ...client.Opt) (client.APIClient, error) {\n\topts, err := ep.ClientOpts()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif len(configFile.HTTPHeaders) > 0 {\n\t\topts = append(opts, client.WithHTTPHeaders(configFile.HTTPHeaders))\n\t}\n\twithCustomHeaders, err := withCustomHeadersFromEnv()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif withCustomHeaders != nil {\n\t\topts = append(opts, withCustomHeaders)","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/cli.go#L280-L316","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\nDOCKER_CONTEXT=staging docker ps   # staging context has stale TLS paths\n// after\ndocker context rm staging && docker context create staging --docker host=ssh://user@staging-host\ndocker context use staging","handlingStrategy":"validation","validationCode":"// Validate the active context exists before building a client.\nfunc validateDockerContext(ctxStore *command.ContextStoreWithDefault, name string) error {\n    if _, err := ctxStore.GetMetadata(name); err != nil {\n        return fmt.Errorf(\"context %q is not resolvable: %w\", name, err)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"client, err := command.NewAPIClientFromFlags(opts, cfg)\nif err != nil {\n    // surface a hint: 'docker context ls' / 'docker context use default' / check TLS files\n}","preventionTips":["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."],"tags":["context","tls","client-initialization","configuration"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}