hashicorp/nomad · error

volume validation failed: %w

Error message

volume validation failed: %w

What it means

validateVolumeUpdate (shared by Create and Register) first runs vol.Validate() against the submitted volume spec. A structurally invalid volume (missing required fields, invalid values) is rejected with this wrapped error. The wrapped cause describes exactly which field failed validation.

Source

Thrown at nomad/host_volume_endpoint.go:419

		}
		return idx, nil
	})
	if err != nil {
		return err
	}

	reply.Volume = vol
	reply.Index = index
	return nil
}

func (v *HostVolume) validateVolumeUpdate(
	vol *structs.HostVolume, snap *state.StateSnapshot) (*structs.HostVolume, error) {

	// validate the volume spec
	err := vol.Validate()
	if err != nil {
		return nil, fmt.Errorf("volume validation failed: %w", err)
	}

	ns, err := snap.NamespaceByName(nil, vol.Namespace)
	if err != nil {
		return nil, err // should never hit, bail out
	}
	if ns == nil {
		return nil, fmt.Errorf("volume validation failed: no such namespace %q", vol.Namespace)
	}

	// validate any update we're making
	var existing *structs.HostVolume
	if vol.ID != "" {
		existing, err = snap.HostVolumeByID(nil, vol.Namespace, vol.ID, true)
		if err != nil {
			return nil, err // should never hit, bail out
		}
		if existing == nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped %w error to identify the offending field.
2. Fix the volume spec per the Nomad host volume documentation (required fields, name constraints).
3. Run client-side validation of the HCL/JSON before submitting.
4. Check the Nomad version's schema if specs were valid on an older version.

Example fix

// before
volume {
  name        = "My Volume"  // invalid characters/space
  host_path   = "/data"
}
// after
volume {
  name        = "my-volume"
  type        = "host"
  host_path   = "/data"
}

if vol.Name == "" || vol.NodeID == "" && vol.HostPath == "" {
    return errors.New("volume spec incomplete: name and host_path/node_id required")
}

func validHostVolume(v *api.HostVolume) bool {
    return v != nil && v.Name != "" && v.HostPath != ""
}

if strings.Contains(err.Error(), "volume validation failed") {
    // surface wrapped cause to the spec author; fix field values
}

When it happens

Trigger: Submitting a HostVolume via Create or Register whose spec fails structs.HostVolume.Validate — e.g. missing HostPath/NodeID fields, invalid characters in the name, or out-of-range values.

Common situations: Hand-written HCL/JSON volume definitions with typos; automation generating specs with empty required fields; schema changes between Nomad versions making previously valid specs invalid.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• validating volume %q against state failed: %v
• volume validation failed: no such namespace %q
• node ID %q is not in pool %q
• Invalid namespace %q: %v
• invalid ID %q

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