hashicorp/nomad · critical

failed to connect to docker daemon

Error message

failed to connect to docker daemon: %s

What it means

CreateNetwork needs a Docker API client to set up the allocation's network isolation (pause container / netns). If getDockerClient cannot establish a connection to the Docker daemon, the allocation network creation is aborted with this wrapped error containing the underlying connection failure.

Solutions

1. Verify the Docker daemon is running (systemctl status docker / docker info)
2. Check the client's docker plugin configuration (docker.endpoint / DOCKER_HOST) points to a reachable daemon socket or address
3. Fix filesystem permissions on /var/run/docker.sock for the Nomad agent user
4. If using a remote daemon, verify network connectivity and TLS certificates

Example fix

# before
DOCKER_HOST=""
# after
DOCKER_HOST="unix:///var/run/docker.sock"

// before creating networks, probe the daemon
cli, err := client.NewClientWithOpts(client.FromEnv)
if err != nil || cli.Ping(ctx) != nil {
    return errors.New("docker daemon unreachable; check docker.endpoint and daemon status")
}

func isDaemonConnErr(err error) bool {
    return err != nil && strings.Contains(err.Error(), "failed to connect to docker daemon")
}

spec, created, err := driver.CreateNetwork(allocID, req)
if isDaemonConnErr(err) {
    // transient infra issue: retry with backoff after checking daemon
    return retryAfterDockerHealthCheck(ctx, err)
}

When it happens

Trigger: Calling Driver.CreateNetwork(allocID, createSpec) when d.getDockerClient() fails: the Docker daemon is not running, DOCKER_HOST points at an unreachable socket/host, or the daemon socket is not accessible.

Common situations: Docker service stopped or not installed on the client host; misconfigured DOCKER_HOST (wrong tcp:// address or missing unix socket); the Nomad client lacks permission on /var/run/docker.sock; remote Docker daemon unreachable through TLS/network.

Related errors

• failed to attach to exec
• failed to fetch docker daemon info
• failed to get docker client
• failed to parse ipv4_address
• failed to remove pause container

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

Appendix: source

Thrown at drivers/docker/network.go:33

const (
	// dockerNetSpecLabelKey is the label added when we create a pause
	// container to own the network namespace, and the NetworkIsolationSpec we
	// get back from CreateNetwork has this label set as the container ID.
	// We'll use this to generate a hostname for the task in the event the user
	// did not specify a custom one. Please see dockerNetSpecHostnameKey.
	dockerNetSpecLabelKey = "docker_sandbox_container_id"

	// dockerNetSpecHostnameKey is the label added when we create a pause
	// container and the task group network include a user supplied hostname
	// parameter.
	dockerNetSpecHostnameKey = "docker_sandbox_hostname"
)

func (d *Driver) CreateNetwork(allocID string, createSpec *drivers.NetworkCreateRequest) (*drivers.NetworkIsolationSpec, bool, error) {
	// Initialize docker API clients
	dockerClient, err := d.getDockerClient()
	if err != nil {
		return nil, false, fmt.Errorf("failed to connect to docker daemon: %s", err)
	}

	if err := d.pullInfraImage(allocID); err != nil {
		return nil, false, err
	}

	config, err := d.createSandboxContainerConfig(allocID, createSpec)
	if err != nil {
		return nil, false, err
	}

	specFromContainer := func(id string, net *container.NetworkSettings, hostname string) *drivers.NetworkIsolationSpec {
		spec := &drivers.NetworkIsolationSpec{
			Mode: drivers.NetIsolationModeGroup,
			Path: net.SandboxKey,
			Labels: map[string]string{
				dockerNetSpecLabelKey: id,
			},

View on GitHub (pinned to 482b49bf1a)