hashicorp/nomad · critical

failed to connect to docker daemon: %s

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.

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)

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 get docker client: %w
• failed to fetch docker daemon info: %v
• Port %q not found, check network block
• Trying to map ports but no network interface is available
• failed to parse ipv4_address %q: %v

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