hashicorp/nomad · critical

failed to get docker client: %v

Error message

failed to get docker client: %v

What it means

During docker driver plugin setup (SetupClient), the driver creates a Docker API client via d.getDockerClient(). Any failure there — bad DOCKER_HOST, unreachable daemon, TLS problems — aborts driver initialization wrapped as "failed to get docker client". The driver cannot operate without a working Docker client connection.

Source

Thrown at drivers/docker/config.go:846

			return fmt.Errorf("failed to parse 'image_pull_timeout' duration: %v", err)
		}
	}

	if err := validateAllowedNamespace(d.config.AllowedModes); err != nil {
		return err
	}
	d.config.allowRuntimes = make(map[string]struct{}, len(d.config.AllowRuntimesList))
	for _, r := range d.config.AllowRuntimesList {
		d.config.allowRuntimes[r] = struct{}{}
	}

	if c.AgentConfig != nil {
		d.clientConfig = c.AgentConfig.Driver
	}

	dockerClient, err := d.getDockerClient()
	if err != nil {
		return fmt.Errorf("failed to get docker client: %v", err)
	}
	coordinatorConfig := &dockerCoordinatorConfig{
		ctx:         d.ctx,
		client:      dockerClient,
		cleanup:     d.config.GC.Image,
		logger:      d.logger,
		removeDelay: d.config.GC.imageDelayDuration,
	}

	d.coordinator = newDockerCoordinator(coordinatorConfig)

	d.danglingReconciler = newReconciler(d)

	go d.recoverPauseContainers(d.ctx)

	return nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the Docker daemon is running: 'docker info' on the host; start/restart dockerd if needed.
2. Check the docker plugin config (docker_endpoint / DOCKER_HOST) points to a valid socket like unix:///var/run/docker.sock.
3. If Nomad runs in a container, mount the host docker socket and grant the nomad user permission (docker group / socket chmod).
4. Validate TLS settings (docker_tls_cacert/cert/key) and confirm the endpoint speaks a compatible API version.
5. Check nomad agent logs for the underlying wrapped error to distinguish connect-refused from permission or version errors.

Example fix

// before
plugin "docker" {
  config {
    docker_endpoint = "unix:///var/run/docker.sock"
  }
}
// after (daemon on TCP with TLS)
plugin "docker" {
  config {
    docker_endpoint = "tcp://docker-host:2376"
    docker_tls_cacert = "/etc/nomad/ca.pem"
    docker_tls_cert   = "/etc/nomad/cert.pem"
    docker_tls_key    = "/etc/nomad/key.pem"
  }
}

// Pre-flight before driver setup
cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil {
    log.Fatalf("docker not reachable: %v", err)
}
if _, err := cli.Ping(context.Background()); err != nil {
    log.Fatalf("docker ping failed: %v", err)
}

catch the setup error, log the wrapped cause, and distinguish: connection refused (start dockerd) vs permission denied (fix socket/group) vs TLS (fix certs).

When it happens

Trigger: Calling driver setup when the Docker daemon is down, DOCKER_HOST points to a nonexistent socket/host, docker client API version negotiation fails, or TLS certs configured for the docker endpoint are invalid/missing.

Common situations: Nomad agent started before dockerd on the host; DOCKER_HOST env or plugin docker_endpoint misconfigured; running Nomad in a container without mounting /var/run/docker.sock; daemon socket permissions denied.

Related errors

• failed to open docker client: %v
• running container as ContainerAdmin is unsafe; change the co
• error decoding stats data: no reader body
• error decoding stats data: stats were nil
• does not match registry specification

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