hashicorp/nomad · error

validating volume %q update failed: %v

Error message

validating volume %q update failed: %v

What it means

After an existing volume is found for an update, Nomad runs vol.ValidateUpdate(existing) to enforce which fields may change (e.g. disallowed mutations of an in-use volume). A policy violation in the update is reported with this wrapped message naming the volume ID. The wrapped error explains which field change is not permitted.

Source

Thrown at nomad/host_volume_endpoint.go:442

		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 {
			return nil, fmt.Errorf("cannot update volume %q: volume does not exist", vol.ID)
		}
		err = vol.ValidateUpdate(existing)
		if err != nil {
			return existing, fmt.Errorf("validating volume %q update failed: %v", vol.ID, err)
		}
	}
	return existing, nil
}

// validateVolumeForState ensures that any references to node IDs or node pools are valid
func (v *HostVolume) validateVolumeForState(vol *structs.HostVolume, snap *state.StateSnapshot) error {
	var poolFromExistingNode string
	if vol.NodeID != "" {
		node, err := snap.NodeByID(nil, vol.NodeID)
		if err != nil {
			return err // should never hit, bail out
		}
		if node == nil {
			return fmt.Errorf("node %q does not exist", vol.NodeID)
		}
		poolFromExistingNode = node.NodePool
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the inner %v error to see which field change was rejected.
2. Revert the disallowed field to its existing value in the spec.
3. Delete and re-create the volume if the field genuinely must change (data-migration permitting).
4. Restrict automation to updating only mutable fields.

Example fix

// before
volume {
  id        = "3f2a..."
  host_path = "/data/new"  // immutable on existing volume
}
// after
volume {
  id        = "3f2a..."
  host_path = "/data"  // keep existing value
}

existing, _, _ := client.HostVolumes().Get(vol.Namespace, vol.ID, nil)
if existing != nil && existing.HostPath != vol.HostPath {
    return errors.New("host_path is immutable; recreate the volume instead")
}

if strings.Contains(err.Error(), "update failed") {
    // revert the disallowed field change indicated by the wrapped error
}

When it happens

Trigger: Calling Create or Register with a volume ID that exists, but attempting to mutate immutable or constrained fields (e.g. changing node ID, host path, or other fields ValidateUpdate forbids given the existing volume's state).

Common situations: Trying to move a volume to another node by editing the spec; changing host_path on an existing volume; drift-checking tools rewriting specs wholesale and touching protected fields.

Related errors

• ErrPluginNotExists
• Error listing host volumes
• cannot update expiration time
• volume name cannot be updated
• volume external ID cannot be updated

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