{"record":{"id":"f4bfe99c052d0e4f","repo":"hashicorp/nomad","slug":"failed-to-build-mount-for-etc-hosts-v","errorCode":null,"errorMessage":"failed to build mount for /etc/hosts: %v","messagePattern":"failed to build mount for /etc/hosts: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/docker/driver.go","lineNumber":1293,"sourceCode":"\t}\n\tfor _, m := range driverConfig.MountsList {\n\t\thm, err := d.toDockerMount(&m, task)\n\t\tif err != nil {\n\t\t\treturn c, err\n\t\t}\n\t\thostConfig.Mounts = append(hostConfig.Mounts, *hm)\n\t}\n\n\t// Setup /etc/hosts\n\t// If the task's network_mode is unset our hostname and IP will come from\n\t// the Nomad-owned network (if in use), so we need to generate an\n\t// /etc/hosts file that matches the network rather than the default one\n\t// that comes from the pause container\n\tif task.NetworkIsolation != nil && driverConfig.NetworkMode == \"\" {\n\t\tetcHostMount, err := hostnames.GenerateEtcHostsMount(\n\t\t\ttask.AllocDir, task.NetworkIsolation, driverConfig.ExtraHosts)\n\t\tif err != nil {\n\t\t\treturn c, fmt.Errorf(\"failed to build mount for /etc/hosts: %v\", err)\n\t\t}\n\t\tif etcHostMount != nil {\n\t\t\t// erase the extra_hosts field if we have a mount so we don't get\n\t\t\t// conflicting options error from dockerd\n\t\t\tdriverConfig.ExtraHosts = nil\n\t\t\thostConfig.Mounts = append(hostConfig.Mounts, mount.Mount{\n\t\t\t\tTarget:   etcHostMount.TaskPath,\n\t\t\t\tSource:   etcHostMount.HostPath,\n\t\t\t\tType:     \"bind\",\n\t\t\t\tReadOnly: etcHostMount.Readonly,\n\t\t\t\tBindOptions: &mount.BindOptions{\n\t\t\t\t\tPropagation: mount.Propagation(etcHostMount.PropagationMode),\n\t\t\t\t},\n\t\t\t})\n\t\t}\n\t}\n\n\t// Setup DNS","sourceCodeStart":1275,"sourceCodeEnd":1311,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/docker/driver.go#L1275-L1311","documentation":"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.","triggerScenarios":"StartTask -> createContainerConfig with task.NetworkIsolation != nil and driverConfig.NetworkMode == \"\", where GenerateEtcHostsMount returns an error (bad alloc dir layout, missing network isolation details, template failure).","commonSituations":"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.","solutions":["Inspect the wrapped %v error from GenerateEtcHostsMount in the logs to find the root cause","Verify the task's alloc_dir exists and is readable/writable by the Nomad client","Check bridge/CNI networking setup (consul_cni_plugin, bridge network) is correctly installed; retry rescheduling the alloc","Set an explicit network_mode in the docker driver config to bypass the /etc/hosts mount generation path"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if task.NetworkIsolation != nil && cfg.NetworkMode == \"\" {\n  if _, err := os.Stat(task.AllocDir); err != nil {\n    return fmt.Errorf(\"alloc dir unusable for /etc/hosts mount: %w\", err)\n  }\n}","typeGuard":null,"tryCatchPattern":"err := client.StartTask(task); if err != nil && strings.Contains(err.Error(), \"failed to build mount for /etc/hosts\") { logRootCause(err); rescheduleAlloc() }","preventionTips":["Keep the alloc directory on healthy writable storage","Verify CNI/bridge plugins are installed on the client","Pin an explicit network_mode to skip the /etc/hosts mount path when isolation isn't needed"],"tags":["docker","nomad-driver","mount","etc-hosts","network-isolation"],"backgroundTag":"mount-generation-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}