hashicorp/nomad · error

host path must be set in configuration for devices

Error message

host path must be set in configuration for devices

What it means

toDockerDevice validates the device stanza before converting it to Docker's device binding structure. A device configuration without HostPath is invalid because Docker needs a host-side path to mount into the container. Nomad returns this error immediately after building the partial DockerDevice, before any container creation.

Source

Thrown at drivers/docker/config.go:558

	Password   string `codec:"password"`
	ServerAddr string `codec:"server_address"`
}

type DockerDevice struct {
	HostPath          string `codec:"host_path"`
	ContainerPath     string `codec:"container_path"`
	CgroupPermissions string `codec:"cgroup_permissions"`
}

func (d DockerDevice) toDockerDevice() (containerapi.DeviceMapping, error) {
	dd := containerapi.DeviceMapping{
		PathOnHost:        d.HostPath,
		PathInContainer:   d.ContainerPath,
		CgroupPermissions: d.CgroupPermissions,
	}

	if d.HostPath == "" {
		return dd, fmt.Errorf("host path must be set in configuration for devices")
	}

	// Docker's CLI defaults to HostPath in this case. See #16754
	if dd.PathInContainer == "" {
		dd.PathInContainer = d.HostPath
	}

	if dd.CgroupPermissions == "" {
		dd.CgroupPermissions = "rwm"
	}

	if !validateCgroupPermission(dd.CgroupPermissions) {
		return dd, fmt.Errorf("invalid cgroup permission string: %q", dd.CgroupPermissions)
	}

	return dd, nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set host_path in the device stanza to an absolute host path (e.g. /dev/nvidia0)
2. Verify the rendered value is non-empty (check HCL/template interpolation)
3. If container_path is also omitted, note Nomad/Docker will default it to host_path — but host_path itself is always required
4. Validate the client config with `nomad agent -config ...` before deployment

Example fix

// before
device {
  name = "gpu"
}
// after
device {
  name            = "gpu"
  host_path       = "/dev/nvidia0"
  container_path  = "/dev/nvidia0"
}

for _, d := range taskConfig.Devices {
    if d.HostPath == "" {
        return fmt.Errorf("device %q missing host_path", d.Name)
    }
    if !filepath.IsAbs(d.HostPath) {
        return fmt.Errorf("device host_path %q must be absolute", d.HostPath)
    }
}

func validDevice(d DeviceConfig) bool {
    return d.HostPath != "" && filepath.IsAbs(d.HostPath)
}

if err := agent.Start(); err != nil {
    if strings.Contains(err.Error(), "host path must be set") {
        // fix the device stanza host_path and reload the client
    }
}

When it happens

Trigger: A task driver config device entry omits the host_path field (or it is an empty string) while toDockerDevice builds the docker.HostConfig device entry — e.g. `device { name = "gpu" }` with no host_path set in the Docker driver config.

Common situations: Typo in the config field name (e.g. path instead of host_path); HCL template rendering HostPath to an empty string; copying a config that relies on defaults that do not exist.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• failed to parse ipv6_address %q: %v
• failed to parse mac_address %q: %v
• must pass non-nil job
• job is missing ID
• ErrLockConflict

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