hashicorp/nomad · error

failed to build mount for /etc/hosts: %v

Error message

failed to build mount for /etc/hosts: %v

What it means

When the task runs under network isolation (netns) and no explicit network_mode is set, Nomad builds an /etc/hosts bind mount via hostnames.GenerateEtcHostsMount so the container sees hosts entries matching the isolated network. Any error from that generator (e.g. alloc dir or network isolation data problems) is wrapped in this message and aborts container creation.

Source

Thrown at drivers/docker/driver.go:1293

	}
	for _, m := range driverConfig.MountsList {
		hm, err := d.toDockerMount(&m, task)
		if err != nil {
			return c, err
		}
		hostConfig.Mounts = append(hostConfig.Mounts, *hm)
	}

	// Setup /etc/hosts
	// If the task's network_mode is unset our hostname and IP will come from
	// the Nomad-owned network (if in use), so we need to generate an
	// /etc/hosts file that matches the network rather than the default one
	// that comes from the pause container
	if task.NetworkIsolation != nil && driverConfig.NetworkMode == "" {
		etcHostMount, err := hostnames.GenerateEtcHostsMount(
			task.AllocDir, task.NetworkIsolation, driverConfig.ExtraHosts)
		if err != nil {
			return c, fmt.Errorf("failed to build mount for /etc/hosts: %v", err)
		}
		if etcHostMount != nil {
			// erase the extra_hosts field if we have a mount so we don't get
			// conflicting options error from dockerd
			driverConfig.ExtraHosts = nil
			hostConfig.Mounts = append(hostConfig.Mounts, mount.Mount{
				Target:   etcHostMount.TaskPath,
				Source:   etcHostMount.HostPath,
				Type:     "bind",
				ReadOnly: etcHostMount.Readonly,
				BindOptions: &mount.BindOptions{
					Propagation: mount.Propagation(etcHostMount.PropagationMode),
				},
			})
		}
	}

	// Setup DNS

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the wrapped %v error from GenerateEtcHostsMount in the logs to find the root cause
2. Verify the task's alloc_dir exists and is readable/writable by the Nomad client
3. Check bridge/CNI networking setup (consul_cni_plugin, bridge network) is correctly installed; retry rescheduling the alloc
4. Set an explicit network_mode in the docker driver config to bypass the /etc/hosts mount generation path

if task.NetworkIsolation != nil && cfg.NetworkMode == "" {
  if _, err := os.Stat(task.AllocDir); err != nil {
    return fmt.Errorf("alloc dir unusable for /etc/hosts mount: %w", err)
  }
}

err := client.StartTask(task); if err != nil && strings.Contains(err.Error(), "failed to build mount for /etc/hosts") { logRootCause(err); rescheduleAlloc() }

When it happens

Trigger: StartTask -> createContainerConfig with task.NetworkIsolation != nil and driverConfig.NetworkMode == "", where GenerateEtcHostsMount returns an error (bad alloc dir layout, missing network isolation details, template failure).

Common situations: Consul/bridge-networking (CNI) tasks where the alloc directory is on a volume with unexpected permissions; tasks whose NetworkIsolation struct lacks the addresses/namespaces the generator expects; corrupted alloc state after node restart.

Related errors

• failed to build mount for resolv.conf: %v
• invalid source, must be "" for tmpfs
• invalid mount type, must be "bind", "volume", "tmpfs": %q
• failed to reattach to docker logger process: %v
• failed to launch docker logger plugin: %v

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