hashicorp/nomad · critical

Failed to create docker client: %v

Error message

Failed to create docker client: %v

What it means

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.

Source

Thrown at drivers/docker/driver.go:355

	if err := cfg.DecodeDriverConfig(&driverConfig); err != nil {
		return nil, nil, fmt.Errorf("failed to decode driver config: %v", err)
	}

	if driverConfig.Image == "" {
		return nil, nil, fmt.Errorf("image name required for docker driver")
	}

	driverConfig.Image = strings.TrimPrefix(driverConfig.Image, "https://")

	driverConfig.ImagePullTimeout = getValue(driverConfig.ImagePullTimeout, d.config.ImagePullTimeout)

	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
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. 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
2. If TLS is configured, verify docker.tls.cert/ca/key files exist, are readable by the Nomad agent user, and are valid PEM
3. Confirm Docker is installed and the daemon socket exists (ls -l /var/run/docker.sock) and the Nomad client user has docker group permissions
4. Test connectivity manually (docker -H <endpoint> info) to reproduce and isolate the client setup problem

Example fix

// before (client agent config)
plugin "docker" {
  config {
    endpoint = "unix:///var/run/dokcer.sock"  // typo
    tls {
      cert = "/etc/certs/client.pem"          // file missing
    }
  }
}
// after
plugin "docker" {
  config {
    endpoint = "unix:///var/run/docker.sock"
    tls {
      cert = "/etc/nomad/certs/client-cert.pem"  // present + readable
      key  = "/etc/nomad/certs/client-key.pem"
      ca   = "/etc/nomad/certs/ca.pem"
    }
  }
}

// pre-flight: confirm docker client env/endpoint and TLS files are valid
for _, f := range []string{tlsCert, tlsKey, tlsCA} {
    if f != "" { if _, err := os.Stat(f); err != nil { return fmt.Errorf("missing TLS file %s", f) } }
}
if os.Getenv("DOCKER_HOST") == "" && endpoint == "" { return errors.New("no docker endpoint configured") }

func canBuildDockerClient(endpoint string, tls *TLSConfig) bool {
    if endpoint == "" { return false }
    if tls != nil {
        for _, p := range []string{tls.Cert, tls.Key, tls.CA} {
            if p != "" && !fileReadable(p) { return false }
        }
    }
    return true
}

_, _, err := driver.StartTask(cfg)
if err != nil && strings.Contains(err.Error(), "Failed to create docker client") {
    // client init often transient (daemon restarting, files being provisioned)
    return retry.WithBackoff(3, 2*time.Second, func() error {
        _, _, err = driver.StartTask(cfg)
        return err
    })
}

When it happens

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

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

Related errors

• failed to get docker long operations client: %w
• failed to launch docker logger process %s: %v
• failed to get docker client: %w
• no PEM-encoded data found
• running container as ContainerAdmin is unsafe; change the co

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