hashicorp/nomad · error

volume mount references an empty volume

Error message

volume mount references an empty volume

What it means

This sentinel error errVolMountEmptyVol is returned directly by VolumeMount.Validate when the mount's Volume field is the empty string, i.e. the task references an undefined volume. Nomad requires every volume mount to name a volume declared in the task group.

Source

Thrown at nomad/structs/volumes.go:26

	multierror "github.com/hashicorp/go-multierror"
)

const (
	VolumeTypeHost = "host"

	VolumeMountPropagationPrivate       = "private"
	VolumeMountPropagationHostToTask    = "host-to-task"
	VolumeMountPropagationBidirectional = "bidirectional"

	SELinuxSharedVolume  = "z"
	SELinuxPrivateVolume = "Z"
)

var (
	errVolMountInvalidPropagationMode = fmt.Errorf("volume mount has an invalid propagation mode")
	errVolMountInvalidSELinuxLabel    = fmt.Errorf("volume mount has an invalid SELinux label")
	errVolMountEmptyVol               = fmt.Errorf("volume mount references an empty volume")
)

// ClientHostVolumeConfig is used to configure access to host paths on a Nomad Client
type ClientHostVolumeConfig struct {
	Name     string `hcl:",key"`
	Path     string `hcl:"path"`
	ReadOnly bool   `hcl:"read_only"`
	// ID is set for dynamic host volumes only.
	ID string `hcl:"-"`
}

func (p *ClientHostVolumeConfig) Equal(o *ClientHostVolumeConfig) bool {
	if p == nil && o == nil {
		return true
	}
	if p == nil || o == nil {
		return false
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add or restore volume = "<name>" in the mount stanza, matching a volume declared in the task group.
2. Inspect the job file's mounts block for an empty or missing volume attribute.
3. If generating jobs programmatically, validate the volume name is non-empty before building the VolumeMount.

Example fix

// before
mount { target = "/data" }
// after
mount { target = "/data", volume = "data" }

if mount.Volume == "" {
    return fmt.Errorf("mount must reference a declared volume")
}

When it happens

Trigger: Calling Validate() on a VolumeMount with Volume == "" — e.g. a mount stanza in a job file that has no volume = "..." key, or programmatic construction of VolumeMount leaving Volume unset.

Common situations: Job specs with a mounts block whose volume key was deleted or never filled; templating tools that render an empty variable into volume = ""; renaming a group volume but not updating the mount reference (that case surfaces as a different error, but empty strings come from absent keys).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• missing node ID for client registration
• missing node name for client registration
• http_read_timeout must be set
• http_max_size must be set
• volume mount has an invalid propagation mode

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