hashicorp/nomad · error

could not validate task driver capabilities: %v

Error message

could not validate task driver capabilities: %v

What it means

If the task requests host volume mounts, prepareHostVolumes queries the task driver's capabilities via h.runner.DriverCapabilities(). If that call errors, this wrapped error is returned. A separate error covers the case where the driver supports no mount configs at all.

Source

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

	hostVolumes := h.runner.clientConfig.Node.HostVolumes

	// Always validate volumes to ensure that we do not allow volumes to be used
	// 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)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check driver plugin health (nomad node status; look for driver "detected/healthy" state)
2. Restart the nomad client agent to re-launch driver plugins
3. Retry allocation start — often transient if the plugin was mid-restart
4. Confirm driver version compatibility with the running Nomad client version

Example fix

// host shell: inspect driver health then restart client
nomad node status -self | grep Drivers
sudo systemctl restart nomad

// before scheduling volume-using tasks, confirm driver health
caps, err := driver.Capabilities()
if err != nil || caps.MountConfigs == drivers.MountConfigSupportNone {
    // don't place host-volume tasks on this node/driver
}

caps, err := runner.DriverCapabilities()
if err != nil {
    // transient plugin failure: brief backoff, retry capability probe
    time.Sleep(500 * time.Millisecond)
    caps, err = runner.DriverCapabilities()
    if err != nil { return err }
}

When it happens

Trigger: len(hostVolumeMounts) > 0 and DriverCapabilities() returns a non-nil error — typically the driver plugin is unhealthy, crashed, or failed RPC while the task was starting.

Common situations: Docker/executor driver plugin crashed or being restarted during alloc start; driver version incompatibility after Nomad upgrade; resource exhaustion preventing the plugin from responding.

Related errors

• plugin is shut down
• failed to start plugin: %v
• plugin loaded does not implement the driver interface
• init of plugin %s failed: %w
• ErrDriverNotFound

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