{"record":{"id":"e8b9818eff90c25b","repo":"docker/cli","slug":"unable-to-create-docker-endpoint-config-w","errorCode":null,"errorMessage":"unable to create docker endpoint config: %w","messagePattern":"unable to create docker endpoint config: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/context/create.go","lineNumber":92,"sourceCode":"\tcase opts.from != \"\":\n\t\terr = createFromExistingContext(s, name, opts.from, opts)\n\tdefault:\n\t\terr = createNewContext(s, name, opts)\n\t}\n\tif err == nil {\n\t\t_, _ = fmt.Fprintln(dockerCLI.Out(), name)\n\t\t_, _ = fmt.Fprintf(dockerCLI.Err(), \"Successfully created context %q\\n\", name)\n\t}\n\treturn err\n}\n\nfunc createNewContext(contextStore store.ReaderWriter, name string, opts createOptions) error {\n\tif opts.endpoint == nil {\n\t\treturn errors.New(\"docker endpoint configuration is required\")\n\t}\n\tdockerEP, dockerTLS, err := getDockerEndpointMetadataAndTLS(contextStore, opts.endpoint)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"unable to create docker endpoint config: %w\", err)\n\t}\n\tcontextMetadata := store.Metadata{\n\t\tEndpoints: map[string]any{\n\t\t\tdocker.DockerEndpoint: dockerEP,\n\t\t},\n\t\tMetadata: command.DockerContext{\n\t\t\tDescription:      opts.description,\n\t\t\tAdditionalFields: opts.metaData,\n\t\t},\n\t\tName: name,\n\t}\n\tcontextTLSData := store.ContextTLSData{}\n\tif dockerTLS != nil {\n\t\tcontextTLSData.Endpoints = map[string]store.EndpointTLSData{\n\t\t\tdocker.DockerEndpoint: *dockerTLS,\n\t\t}\n\t}\n\tif err := validateEndpoints(contextMetadata); err != nil {","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/context/create.go#L74-L110","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Validate the host URL scheme: tcp://, unix://, npipe://, ssh://","Check TLS files exist and are readable: ls -l ca.pem cert.pem key.pem","Ensure cert and key are a matching pair","For non-TLS remote daemons, use --docker host=tcp://host:2375 or set skip-tls-verify=true"],"exampleFix":"# before\ndocker context create ctx --docker host=tcp:/bad\n# after\ndocker context create ctx --docker host=tcp://myserver:2376,ca=./ca.pem,cert=./cert.pem,key=./key.pem","handlingStrategy":"validation","validationCode":"// Validate endpoint config before creating a context.\nfor _, k := range []string{\"ca\", \"cert\", \"key\"} {\n    if p, ok := endpoint[k]; ok && p != \"\" {\n        if _, err := os.Stat(p); err != nil {\n            return fmt.Errorf(\"%s file %q not readable: %w\", k, p, err)\n        }\n    }\n}\nif u, err := url.Parse(endpoint[\"host\"]); err != nil || u.Scheme == \"\" {\n    return fmt.Errorf(\"bad host %q\", endpoint[\"host\"])\n}","typeGuard":null,"tryCatchPattern":"if err := runCreate(...); err != nil {\n    if strings.Contains(err.Error(), \"unable to create docker endpoint config\") {\n        // surface the wrapped cause to the user\n    }\n}","preventionTips":["Keep TLS material in a fixed, version-controlled path","Use url.Parse on the host before context creation"],"tags":["docker","context","endpoint","tls","config-validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}