hashicorp/nomad · error

task driver %q for %q does not support host volumes

Error message

task driver %q for %q does not support host volumes

What it means

Nomad's volume_hook (volumeHook.prepHostVolumes/prepareHostVolumes) validates during task Prestart that if the task has host (Docker-style) volume mounts configured, the selected task driver advertises MountConfigs support greater than MountConfigSupportNone via its DriverCapabilities. If the driver cannot mount host volumes (or cannot report capabilities), Prestart fails and the allocation is rejected. It is a capability gate, not a transient failure.

Source

Thrown at client/allocrunner/taskrunner/volume_hook.go:145

	// if a host is restarted and loses the host volume configuration.
	if err := validateHostVolumes(volumes, hostVolumes, req.Alloc.Name); err != nil {
		h.logger.Error("Requested Host Volume does not exist", "existing", hostVolumes, "requested", volumes)
		return nil, fmt.Errorf("host volume validation error: %v", err)
	}

	hostVolumeMounts, err := h.hostVolumeMountConfigurations(req.Task.VolumeMounts, volumes, hostVolumes, req.Alloc.Name)
	if err != nil {
		h.logger.Error("Failed to generate host volume mounts", "error", err)
		return nil, err
	}

	if len(hostVolumeMounts) > 0 {
		caps, err := h.runner.DriverCapabilities()
		if err != nil {
			return nil, fmt.Errorf("could not validate task driver capabilities: %v", err)
		}
		if caps.MountConfigs == drivers.MountConfigSupportNone {
			return nil, fmt.Errorf(
				"task driver %q for %q does not support host volumes",
				h.runner.task.Driver, h.runner.task.Name)
		}
	}

	return hostVolumeMounts, nil
}

// partitionMountsByVolume takes a list of volume mounts and returns them in the
// form of volume-alias:[]volume-mount because one volume may be mounted multiple
// times.
func partitionMountsByVolume(xs []*structs.VolumeMount) map[string][]*structs.VolumeMount {
	result := make(map[string][]*structs.VolumeMount)
	for _, mount := range xs {
		result[mount.Volume] = append(result[mount.Volume], mount)
	}

	return result

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Change the task driver to one that supports host volumes (e.g. docker) or remove the volume_mount stanza from the task
2. Upgrade the driver/plugin (and Nomad client) so DriverCapabilities() reports MountConfigs != MountConfigSupportNone
3. Verify client config registers the host volume (client { host_volume "x" {} }) and that the driver intended for the task is actually the one selected
4. If you only need shared files, use a template stanza or artifact instead of a host volume

Example fix

// before
job "app" {
  group "g" {
    volume "data" { type = "host" source = "data" }
    task "worker" {
      driver = "raw_exec"
      volume_mount { volume = "data" }
    }
  }
}
// after
task "worker" {
  driver = "docker"
  volume_mount { volume = "data" }
}

// Before submitting the job, verify driver mount capability on target nodes:
// nomad node status <node> shows Driver status; assert capability via driver docs, e.g.:
if task.Driver != "docker" && hasHostVolumeMounts(task) {
    return fmt.Errorf("driver %q does not support host volumes; use docker or drop volume_mount", task.Driver)
}

When it happens

Trigger: A job's task declares a host volume mount (volume_mount with a host_volume source) but the task's driver (e.g. exec, raw_exec, java, or an older driver version) reports drivers.MountConfigSupportNone for MountConfigs; h.runner.DriverCapabilities() is called during volumeHook.Prestart and the returned caps.MountConfigs equals MountConfigSupportNone.

Common situations: Running a docker-image-less driver like raw_exec/exec or java that doesn't support host volume binds, but the job template was copied from a docker task that used host volumes; Nomad agent with an outdated or misconfigured plugin whose Capabilities() omits mount support; using host volumes on Windows with a driver lacking bind-mount support; Nomad version mismatch where the driver capability struct predates MountConfigs.

Related errors

• task driver %q for %q does not support CSI
• ErrPluginNotExists
• Error listing host volumes
• task %s does not support %q networking mode
• No CSI Mount Point found for volume: %s

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