{"record":{"id":"a9c82d060f3d65d5","repo":"hashicorp/nomad","slug":"failed-to-create-docker-client-v","errorCode":null,"errorMessage":"Failed to create docker client: %v","messagePattern":"Failed to create docker client: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"drivers/docker/driver.go","lineNumber":355,"sourceCode":"\tif err := cfg.DecodeDriverConfig(&driverConfig); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to decode driver config: %v\", err)\n\t}\n\n\tif driverConfig.Image == \"\" {\n\t\treturn nil, nil, fmt.Errorf(\"image name required for docker driver\")\n\t}\n\n\tdriverConfig.Image = strings.TrimPrefix(driverConfig.Image, \"https://\")\n\n\tdriverConfig.ImagePullTimeout = getValue(driverConfig.ImagePullTimeout, d.config.ImagePullTimeout)\n\n\thandle := drivers.NewTaskHandle(taskHandleVersion)\n\thandle.Config = cfg\n\n\t// we'll need the normal docker client\n\tdockerClient, err := d.getDockerClient()\n\tif err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"Failed to create docker client: %v\", err)\n\t}\n\n\tdockerInfo, err := dockerClient.Info(d.ctx, mclient.InfoOptions{})\n\tif err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to fetch docker daemon info: %v\", err)\n\t}\n\n\t// and also the long operations client\n\tinfinityClient, err := d.getInfinityClient()\n\tif err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"Failed to create long operations docker client: %v\", err)\n\t}\n\n\tid, user, err := d.createImage(cfg, &driverConfig, dockerClient)\n\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n","sourceCodeStart":337,"sourceCodeEnd":373,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/docker/driver.go#L337-L373","documentation":"StartTask calls d.getDockerClient() to build a Docker API client before contacting the daemon. This error wraps the underlying failure to construct that client — typically failed TLS/CA cert loading, invalid endpoint URL, or client initialization errors — indicating the driver cannot talk to Docker at all yet.","triggerScenarios":"getDockerClient fails because: docker endpoint (DOCKER_HOST / driver config) is malformed; TLS cert/key/CA files specified in docker.tls config are missing, unreadable, or invalid; the mclient (Docker SDK) client cannot be initialized for the configured host.","commonSituations":"Misconfigured docker.endpoint or DOCKER_HOST (bad unix socket path, wrong tcp:// URL); TLS files not mounted into the client's environment (common in Nomad client installs with docker.tls set); permissions preventing reading of cert files; Docker SDK/daemon API version mismatch causing client init failure.","solutions":["Check the wrapped inner error and verify the docker endpoint config: correct unix:///var/run/docker.sock or tcp://host:2376 URL and that DOCKER_HOST is sane","If TLS is configured, verify docker.tls.cert/ca/key files exist, are readable by the Nomad agent user, and are valid PEM","Confirm Docker is installed and the daemon socket exists (ls -l /var/run/docker.sock) and the Nomad client user has docker group permissions","Test connectivity manually (docker -H <endpoint> info) to reproduce and isolate the client setup problem"],"exampleFix":"// before (client agent config)\nplugin \"docker\" {\n  config {\n    endpoint = \"unix:///var/run/dokcer.sock\"  // typo\n    tls {\n      cert = \"/etc/certs/client.pem\"          // file missing\n    }\n  }\n}\n// after\nplugin \"docker\" {\n  config {\n    endpoint = \"unix:///var/run/docker.sock\"\n    tls {\n      cert = \"/etc/nomad/certs/client-cert.pem\"  // present + readable\n      key  = \"/etc/nomad/certs/client-key.pem\"\n      ca   = \"/etc/nomad/certs/ca.pem\"\n    }\n  }\n}","handlingStrategy":"retry","validationCode":"// pre-flight: confirm docker client env/endpoint and TLS files are valid\nfor _, f := range []string{tlsCert, tlsKey, tlsCA} {\n    if f != \"\" { if _, err := os.Stat(f); err != nil { return fmt.Errorf(\"missing TLS file %s\", f) } }\n}\nif os.Getenv(\"DOCKER_HOST\") == \"\" && endpoint == \"\" { return errors.New(\"no docker endpoint configured\") }","typeGuard":"func canBuildDockerClient(endpoint string, tls *TLSConfig) bool {\n    if endpoint == \"\" { return false }\n    if tls != nil {\n        for _, p := range []string{tls.Cert, tls.Key, tls.CA} {\n            if p != \"\" && !fileReadable(p) { return false }\n        }\n    }\n    return true\n}","tryCatchPattern":"_, _, err := driver.StartTask(cfg)\nif err != nil && strings.Contains(err.Error(), \"Failed to create docker client\") {\n    // client init often transient (daemon restarting, files being provisioned)\n    return retry.WithBackoff(3, 2*time.Second, func() error {\n        _, _, err = driver.StartTask(cfg)\n        return err\n    })\n}","preventionTips":["Verify DOCKER_HOST/endpoint config and test with docker -H <endpoint> info during provisioning","Ensure TLS cert/key/CA files exist and are readable by the Nomad agent user before it starts","Keep the Nomad client user in the docker group","Pin a Docker daemon version compatible with the Nomad docker driver / Docker SDK"],"tags":["docker","client-init","tls","endpoint"],"backgroundTag":"docker-client-creation-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}