hashicorp/nomad · error

can not update mount options while volume is in use

Error message

can not update mount options while volume is in use

What it means

Raised by CSIVolume.Merge (nomad/structs/csi.go:842) when mount options (fs type, mount flags) are changed on a volume that is currently in use. Nomad allows MountOptions updates only while no allocation is claiming the volume, because the mount is already established on running workloads and cannot be safely altered.

Source

Thrown at nomad/structs/csi.go:842

				"volume requested capabilities update was not compatible with existing capability in use"))
		}
	} else {
		v.RequestedCapabilities = other.RequestedCapabilities
	}

	// topologies are immutable, so topology request changes must be
	// compatible with the existing topology, if any
	if len(v.Topologies) > 0 {
		if !v.RequestedTopologies.Equal(other.RequestedTopologies) {
			errs = multierror.Append(errs, errors.New(
				"volume topology request update was not compatible with existing topology"))
		}
	}

	// MountOptions can be updated so long as the volume isn't in use
	if v.InUse() {
		if !v.MountOptions.Equal(other.MountOptions) {
			errs = multierror.Append(errs, errors.New(
				"can not update mount options while volume is in use"))
		}
	} else {
		v.MountOptions = other.MountOptions
	}

	// Secrets can be updated freely
	v.Secrets = other.Secrets

	// must be compatible with parameters set by from CreateVolumeResponse

	if len(other.Parameters) != 0 && !maps.Equal(v.Parameters, other.Parameters) {
		errs = multierror.Append(errs, errors.New(
			"volume parameters cannot be updated"))
	}

	// Context is mutable and will be used during controller validation, but we
	// need to ensure we don't remove context that's been previously stored

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Stop all allocations that use the volume so claims are released, then resubmit the update
2. Keep MountOptions unchanged in the update (equal values pass even while in use)
3. If a permanent option change is needed while workloads run, create a separate volume with the new mount options and migrate the jobs

Example fix

// before (volume in use)
mount_options {
  fs_type     = "ext4"
  mount_flags = ["ro"] # changed while volume is mounted
}
// after: stop allocations first, or keep options unchanged until volume is free
mount_options {
  fs_type     = "ext4"
  mount_flags = ["rw"] # submitted after all claims released
}

// check in-use state before changing mount options
if existing.InUse() && !existing.MountOptions.Equal(update.MountOptions) {
    return errors.New("stop all allocations using this volume before changing mount options")
}

func mountOptionsMutable(existing, update *structs.CSIVolume) bool {
    return !existing.InUse() || existing.MountOptions.Equal(update.MountOptions)
}

When it happens

Trigger: `nomad volume update` (or job spec volume merge) where v.InUse() is true (volume has active claims from allocations) and !v.MountOptions.Equal(other.MountOptions).

Common situations: Trying to change mount flags such as 'ro'/'rw' or fs type while the volume is mounted by a running allocation; adding/removing mount flags during live workloads; scripts that resubmit full volume specs with tweaked mount options.

Related errors

• volume clone ID cannot be updated
• volume snapshot ID cannot be updated
• volume requested capabilities update was not compatible with
• volume topology request update was not compatible with exist
• volume parameters cannot be updated

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