hashicorp/nomad · error

volume mount has an invalid propagation mode

Error message

volume mount has an invalid propagation mode

What it means

This error is returned by VolumeMount.Validate in nomad/structs/volumes.go when a task's volume mount specifies a propagation mode that Nomad does not recognize. The declared sentinel error errVolMountInvalidPropagationMode is wrapped with the offending value via fmt.Errorf("%w: %q"). Propagation modes must be one of the valid VolumeMount PropagationMode values (e.g. private, host-to-task, bidirectional).

Source

Thrown at nomad/structs/volumes.go:24

import (
	"fmt"

	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 {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set the mount's propagation_mode to a valid value: "private", "host-to-task", or "bidirectional".
2. Check the exact value in the error message suffix (the %q portion) for typos or stray whitespace.
3. Remove the propagation_mode field entirely to use the default (private).

Example fix

// before
mounts = [{ volume = "data", propagation_mode = "rprivate" }]
// after
mounts = [{ volume = "data", propagation_mode = "private" }]

validModes := map[string]bool{"private": true, "host-to-task": true, "bidirectional": true}
if !validModes[mount.PropagationMode] {
    return fmt.Errorf("invalid propagation_mode %q", mount.PropagationMode)
}

func isValidPropagationMode(m string) bool {
    return m == "private" || m == "host-to-task" || m == "bidirectional"
}

When it happens

Trigger: Calling Validate() on a VolumeMount whose PropagationMode field is not one of the allowed constants, e.g. the test value "very invalid propagation mode". Typically caused by a typo in an HCL/JSON job spec's mount propagation_mode.

Common situations: Hand-edited Nomad job files with misspelled propagation_mode; jobs generated by tooling that emits Docker-style propagation strings (e.g. 'rprivate', 'rslave') instead of Nomad's modes; copy-pasted config between container runtimes.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• volume has unrecognized type %s
• wait config is nil or empty
• missing datacenter for client registration
• default_identity_ttl must be greater than 0
• max_identity_ttl must be greater than 0

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