hashicorp/nomad · error

no host volume named: %s

Error message

no host volume named: %s

What it means

hostVolumeMountConfigurations builds driver MountConfigs from the task's volume_mounts. It looks each source up in the client's host volumes; if absent it returns "no host volume named: <source>". The comment notes this should never happen because validation ran first — it guards against client volumes being mutated between validation and mount generation.

Source

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

			// type.
			continue
		}

		// This is a defensive check, but this function should only ever receive
		// host-type volumes.
		if req.Type != structs.VolumeTypeHost {
			continue
		}

		source := req.Source
		if req.PerAlloc {
			source = source + structs.AllocSuffix(allocName)
		}
		hostVolume, ok := clientVolumesByName[source]
		if !ok {
			// Should never happen, but unless the client volumes were mutated during
			// the execution of this hook.
			return nil, fmt.Errorf("no host volume named: %s", source)
		}

		mcfg := &drivers.MountConfig{
			RequestName:     hostVolume.Name,
			HostPath:        hostVolume.Path,
			TaskPath:        m.Destination,
			Readonly:        hostVolume.ReadOnly || req.ReadOnly || m.ReadOnly,
			PropagationMode: m.PropagationMode,
			SELinuxLabel:    m.SELinuxLabel,
		}
		mounts = append(mounts, mcfg)
	}

	return mounts, nil
}

// partitionVolumesByType takes a map of volume-alias to volume-request and
// returns them in the form of volume-type:(volume-alias:volume-request)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Restart the allocation after ensuring the client's host_volume config is stable
2. Avoid reloading/reconfiguring the Nomad agent while allocations are starting
3. Verify the volume name matches the client config exactly (case, per_alloc suffix)
4. If it recurs, collect a nomad agent log bundle — it indicates an internal race

// before scheduling, confirm client host volumes are stable
vols := clientConfig.Node.HostVolumes
for _, m := range task.VolumeMounts {
    if _, ok := vols[m.Source]; !ok { skipNode() }
}

mcfgs, err := hostVolumeMountConfigurations(mounts, volumes, hostVolumes, name)
if err != nil {
    // transient client-volume mutation; re-read client config and retry once
    hostVolumes = refreshClientVolumes()
    return hostVolumeMountConfigurations(mounts, volumes, hostVolumes, name)
}

When it happens

Trigger: Client node HostVolumes map changed (or was empty) between validateHostVolumes and hostVolumeMountConfigurations during the same Prestart — e.g. the node config was reloaded concurrently or validation was skipped via a different code path.

Common situations: Race with agent config reload (SIGHUP) during alloc start; bespoke tooling mutating client config at runtime; identical to the missing-volume case but symptomatic of an in-flight change.

Related errors

• missing %s
• host volume validation error: %v
• cannot register volume: node ID is required
• cannot register volume: host path is required
• task group volume claim does not exist

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