{"record":{"id":"dc23cd5985832b54","repo":"hashicorp/nomad","slug":"failed-to-create-long-operations-docker-client-v","errorCode":null,"errorMessage":"Failed to create long operations docker client: %v","messagePattern":"Failed to create long operations docker client: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/docker/driver.go","lineNumber":366,"sourceCode":"\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\n\t// validate the image user (windows only)\n\tif err := validateImageUser(user, cfg.User, &driverConfig, d.config); err != nil {\n\t\treturn nil, nil, err\n\t}\n\n\tif runtime.GOOS == \"windows\" {\n\t\terr = d.convertAllocPathsForWindowsLCOW(cfg, driverConfig.Image)\n\t\tif err != nil {\n\t\t\treturn nil, nil, err\n\t\t}\n\t}","sourceCodeStart":348,"sourceCodeEnd":384,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/docker/driver.go#L348-L384","documentation":"This error wraps any failure from d.getInfinityClient(), which builds the long-lived ('infinity' timeout) Docker client used for long operations during task startup in StartTask. It is thrown when the driver cannot construct that second Docker client after the normal client and daemon Info check already succeeded, so the underlying cause is a client-construction failure (bad DOCKER_HOST, TLS/cert problems, or unparseable endpoint config), not a daemon outage. The original error text is appended via %v.","triggerScenarios":"StartTask calls getInfinityClient() and it returns an error - typically because the docker client config (endpoint derived from DOCKER_HOST / config.endpoint, or TLS material from docker.auth or client config) fails to produce a valid SDK client.","commonSituations":"Invalid or unreachable DOCKER_HOST URL scheme; malformed TLS certificate/key paths configured for the Docker driver; missing docker socket permissions making client setup fail; socket or endpoint strings with unsupported schemes (e.g. tcp to a non-existent host); Windows named pipe misconfiguration.","solutions":["Verify DOCKER_HOST / driver endpoint config is a valid Docker API URL (unix:///var/run/docker.sock or tcp://host:port)","Check TLS certificate, key, and CA file paths configured for the driver exist and are readable","Fix socket permissions / run the agent with access to the docker socket or docker group","Read the wrapped %v cause to identify whether it is a URL parse error vs a connection error, and fix accordingly"],"exampleFix":"// before\nDOCKER_HOST=\"tcp://127.0.0.1:237\"  // wrong port/scheme\n// after\nDOCKER_HOST=\"unix:///var/run/docker.sock\"","handlingStrategy":"validation","validationCode":"// Before submitting the task, verify a Docker client can be built from the same config:\nendpoint := os.Getenv(\"DOCKER_HOST\")\nif endpoint == \"\" { endpoint = \"unix:///var/run/docker.sock\" }\nif u, err := url.Parse(endpoint); err != nil || (u.Scheme != \"unix\" && u.Scheme != \"tcp\" && u.Scheme != \"npipe\" && u.Scheme != \"\") {\n    return fmt.Errorf(\"invalid DOCKER_HOST %q: %w\", endpoint, err)\n}\ncli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())\nif err != nil { return fmt.Errorf(\"docker client build failed: %w\", err) }\n_, err = cli.Info(context.Background())","typeGuard":"func isClientBuildErr(err error) bool {\n    var uerr *url.Error\n    return err != nil && (errors.As(err, &uerr) || strings.Contains(err.Error(), \"unable to parse\") || strings.Contains(err.Error(), \"invalid endpoint\"))\n}","tryCatchPattern":"client, err := d.getInfinityClient()\nif err != nil {\n    return fmt.Errorf(\"Failed to create long operations docker client: %w\", err) // inspect wrapped cause\n}","preventionTips":["Validate DOCKER_HOST scheme/format before starting the driver","Keep TLS cert/key/CA paths in driver config correct and readable by the agent process","Test docker client creation with a startup healthcheck (client.Info) before task submission","Keep the docker SDK client options (FromEnv / custom endpoint) consistent across all clients in the driver"],"tags":["docker","client-initialization","driver"],"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-08T15:18:49.778Z"}