{"record":{"id":"8f22c1fb39a9f2e6","repo":"docker/cli","slug":"unable-to-apply-docker-endpoint-options-w","errorCode":null,"errorMessage":"unable to apply docker endpoint options: %w","messagePattern":"unable to apply docker endpoint options: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/context/options.go","lineNumber":127,"sourceCode":"\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":109,"sourceCodeEnd":139,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/context/options.go#L109-L139","documentation":"Returned when client.New(opts...) fails while validating endpoint options in getDockerEndpoint. This is a secondary validation pass (noted by the FIXME at options.go:125) that actually instantiates a Docker client from the derived options to catch problems the earlier checks missed. Failure indicates the options, though syntactically valid, cannot form a working client.","triggerScenarios":"Endpoint options pass ClientOpts() but client.New rejects them, e.g., because the resolved host is unreachable for option-validation reasons, custom HTTP headers/transport settings are invalid, or the TLS material is internally inconsistent (cert without matching key, expired CA). The client is created but not connected, so this is about option-construction, not network reachability.","commonSituations":"Supplying a cert file that does not pair with the given key; a CA path pointing to a directory rather than a file; version skew where client.New enforces checks the older context did not; corrupted TLS files that parse as empty.","solutions":["Verify TLS file integrity: ensure ca, cert, and key are valid PEM and that the cert matches the key (e.g., 'openssl x509 -in cert.pem -noout -modulus' vs 'openssl rsa -in key.pem -noout -modulus').","Drop the TLS flags and use skip-tls-verify=true as a diagnostic to isolate whether TLS material is the cause.","Re-create the context pointing at a known-good daemon host to confirm the options shape, then re-add TLS.","Upgrade the CLI to match the daemon/API version if this appeared after a version change."],"exampleFix":"# before\ndocker context create --docker host=tcp://host:2376,ca=ca.pem,cert=cert.pem,key=wrong.key my-ctx\n# after\ndocker context create --docker host=tcp://host:2376,ca=ca.pem,cert=cert.pem,key=key.pem my-ctx","handlingStrategy":"validation","validationCode":"// Verify TLS material pairs correctly before building the endpoint.\nfunc validateTLSPair(ca, cert, key string) error {\n\tif cert == \"\" && key != \"\" || cert != \"\" && key == \"\" {\n\t\treturn errors.New(\"cert and key must both be set or both empty\")\n\t}\n\t// optionally: compare modulus of cert and key PEM blocks\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":"if err := cli.ContextCreate(...); err != nil {\n\tif strings.Contains(err.Error(), \"unable to apply docker endpoint options\") {\n\t\t// TLS material is likely inconsistent; re-check cert/key pairing\n\t}\n}","preventionTips":["Confirm cert and key are a matching pair using openssl before referencing them.","Point ca/cert/key to files, not directories.","Test the endpoint with a throwaway context before promoting it."],"tags":["docker-context","tls","client-options","validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}