{"record":{"id":"e5c07d2bc4ce605d","repo":"docker/cli","slug":"invalid-docker-endpoint-options-w","errorCode":null,"errorMessage":"invalid docker endpoint options: %w","messagePattern":"invalid docker endpoint options: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/context/options.go","lineNumber":123,"sourceCode":"\ttlsData, err := context.TLSDataFromFiles(config[keyCA], config[keyCert], config[keyKey])\n\tif err != nil {\n\t\treturn docker.Endpoint{}, err\n\t}\n\tskipTLSVerify, err := parseBool(config, keySkipTLSVerify)\n\tif err != nil {\n\t\treturn docker.Endpoint{}, err\n\t}\n\tep := docker.Endpoint{\n\t\tEndpointMeta: docker.EndpointMeta{\n\t\t\tHost:          config[keyHost],\n\t\t\tSkipTLSVerify: skipTLSVerify,\n\t\t},\n\t\tTLSData: tlsData,\n\t}\n\t// try to resolve a docker client, validating the configuration\n\topts, err := ep.ClientOpts()\n\tif err != nil {\n\t\treturn docker.Endpoint{}, fmt.Errorf(\"invalid docker endpoint options: %w\", err)\n\t}\n\t// FIXME(thaJeztah): this creates a new client (but discards it) only to validate the options; are the validation steps above not enough?\n\tif _, err := client.New(opts...); err != nil {\n\t\treturn docker.Endpoint{}, fmt.Errorf(\"unable to apply docker endpoint options: %w\", err)\n\t}\n\treturn ep, nil\n}\n\nfunc getDockerEndpointMetadataAndTLS(contextStore store.Reader, config map[string]string) (docker.EndpointMeta, *store.EndpointTLSData, error) {\n\tep, err := getDockerEndpoint(contextStore, config)\n\tif err != nil {\n\t\treturn docker.EndpointMeta{}, nil, err\n\t}\n\treturn ep.EndpointMeta, ep.TLSData.ToStoreTLSData(), nil\n}\n","sourceCodeStart":105,"sourceCodeEnd":139,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/context/options.go#L105-L139","documentation":"Returned when docker.Endpoint.ClientOpts() fails during endpoint validation in getDockerEndpoint. ClientOpts() validates the assembled endpoint (host, TLS data, skip-tls-verify) and produces the client connection options; failure means the configuration is internally inconsistent or the host value is malformed/unparseable as a Docker daemon endpoint. The wrapping preserves the underlying cause via %w.","triggerScenarios":"Creating/updating a context with '--docker host=<malformed-url>' where the host is not a valid Docker endpoint URL (e.g., missing scheme, unsupported scheme, empty host). Also triggered by contradictory TLS settings, such as providing TLS cert/key paths but an invalid or non-TLS host.","commonSituations":"Typo in the host value (e.g., 'host=docker:2376' missing the 'tcp://' scheme); pointing at a Unix socket with wrong formatting; copy-pasting a host from docs that uses a scheme this CLI version does not accept.","solutions":["Check the host value format: it must be a full URL like 'tcp://host:2376', 'unix:///var/run/docker.sock', or 'ssh://user@host'.","Remove the context and recreate it with a corrected --docker host= value.","If using TLS, ensure host uses a TLS-compatible scheme (tcp:// with port 2376) and that cert/key/ca paths are readable.","Run 'docker context inspect <name>' to see the stored host and compare against a known-good context."],"exampleFix":"# before\ndocker context create --docker host=docker.example:2376 my-ctx\n# after\ndocker context create --docker host=tcp://docker.example:2376 my-ctx","handlingStrategy":"validation","validationCode":"// Validate a host string is a parseable Docker endpoint before passing it\n// as --docker host=.\nimport \"github.com/moby/moby/client\"\n\nfunc validateHost(host string) error {\n\topts, err := docker.Endpoint{EndpointMeta: docker.EndpointMeta{Host: host}}.ClientOpts()\n\tif err != nil { return err }\n\t_ = opts\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":"if err := cli.ContextCreate(...); err != nil {\n\tif strings.Contains(err.Error(), \"invalid docker endpoint options\") {\n\t\t// re-prompt for a corrected --docker host= value\n\t}\n}","preventionTips":["Always include the scheme in host= (tcp://, unix://, ssh://).","Use 'docker context inspect' to compare a broken host against a working one.","Validate the host string programmatically before context creation."],"tags":["docker-context","endpoint","host-validation","configuration"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}