hashicorp/nomad · error

Failed to create long operations docker client: %v

Error message

Failed to create long operations docker client: %v

What it means

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.

Source

Thrown at drivers/docker/driver.go:366

	handle := drivers.NewTaskHandle(taskHandleVersion)
	handle.Config = cfg

	// we'll need the normal docker client
	dockerClient, err := d.getDockerClient()
	if err != nil {
		return nil, nil, fmt.Errorf("Failed to create docker client: %v", err)
	}

	dockerInfo, err := dockerClient.Info(d.ctx, mclient.InfoOptions{})
	if err != nil {
		return nil, nil, fmt.Errorf("failed to fetch docker daemon info: %v", err)
	}

	// and also the long operations client
	infinityClient, err := d.getInfinityClient()
	if err != nil {
		return nil, nil, fmt.Errorf("Failed to create long operations docker client: %v", err)
	}

	id, user, err := d.createImage(cfg, &driverConfig, dockerClient)
	if err != nil {
		return nil, nil, err
	}

	// validate the image user (windows only)
	if err := validateImageUser(user, cfg.User, &driverConfig, d.config); err != nil {
		return nil, nil, err
	}

	if runtime.GOOS == "windows" {
		err = d.convertAllocPathsForWindowsLCOW(cfg, driverConfig.Image)
		if err != nil {
			return nil, nil, err
		}
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify DOCKER_HOST / driver endpoint config is a valid Docker API URL (unix:///var/run/docker.sock or tcp://host:port)
2. Check TLS certificate, key, and CA file paths configured for the driver exist and are readable
3. Fix socket permissions / run the agent with access to the docker socket or docker group
4. Read the wrapped %v cause to identify whether it is a URL parse error vs a connection error, and fix accordingly

Example fix

// before
DOCKER_HOST="tcp://127.0.0.1:237"  // wrong port/scheme
// after
DOCKER_HOST="unix:///var/run/docker.sock"

// Before submitting the task, verify a Docker client can be built from the same config:
endpoint := os.Getenv("DOCKER_HOST")
if endpoint == "" { endpoint = "unix:///var/run/docker.sock" }
if u, err := url.Parse(endpoint); err != nil || (u.Scheme != "unix" && u.Scheme != "tcp" && u.Scheme != "npipe" && u.Scheme != "") {
    return fmt.Errorf("invalid DOCKER_HOST %q: %w", endpoint, err)
}
cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil { return fmt.Errorf("docker client build failed: %w", err) }
_, err = cli.Info(context.Background())

func isClientBuildErr(err error) bool {
    var uerr *url.Error
    return err != nil && (errors.As(err, &uerr) || strings.Contains(err.Error(), "unable to parse") || strings.Contains(err.Error(), "invalid endpoint"))
}

client, err := d.getInfinityClient()
if err != nil {
    return fmt.Errorf("Failed to create long operations docker client: %w", err) // inspect wrapped cause
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to inspect container %q: %v
• DriverStatsNotImplemented
• running container as ContainerAdmin is unsafe; change the co
• error decoding stats data: no reader body
• error decoding stats data: stats were nil

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/dc23cd5985832b54. Report an issue: GitHub.