requested mount flags did not match available capabilities

Error message

requested mount flags did not match available capabilities

What it means

compareCapabilities verifies that the volume capabilities returned by the CSI controller (e.g. from ControllerValidateCapabilities) satisfy what Nomad requested. This error is appended when a mount flag requested in the expected VolumeCapability (e.g. 'ro', mount options from the task's volume config) is not present in the plugin's returned capability's MountFlags. Per CSI spec comments in the source, exact flag details are not logged because mount flags can contain sensitive data. It means the storage plugin advertised/validated a capability that does not support the requested mount options.

Source

Thrown at plugins/csi/client.go:616

		if expectedMount == nil {
			multierror.Append(&err, fmt.Errorf(
				"'file-system' access type was not requested but was validated by the controller"))
			continue NEXT_CAP
		}

		if expectedMount.FsType != capMount.FsType {
			multierror.Append(&err, fmt.Errorf(
				"requested filesystem type %v, got %v",
				expectedMount.FsType, capMount.FsType))
			continue NEXT_CAP
		}

		for _, expectedFlag := range expectedMount.MountFlags {

			// The mount flags can contain sensitive data, so we can't log exact
			// details.
			if !slices.Contains(capMount.MountFlags, expectedFlag) {
				multierror.Append(&err, fmt.Errorf(
					"requested mount flags did not match available capabilities"))
				continue NEXT_CAP
			}
		}

		return nil
	}
	return err.ErrorOrNil()
}

func (c *client) ControllerCreateSnapshot(ctx context.Context, req *ControllerCreateSnapshotRequest, opts ...grpc.CallOption) (*ControllerCreateSnapshotResponse, error) {
	if err := c.ensureConnected(ctx); err != nil {
		return nil, err
	}

	err := req.Validate()
	if err != nil {
		return nil, err

View on GitHub (pinned to 482b49bf1a)

Solutions

Remove or correct unsupported mount_options in the job's volume/volume_mount block to match what the CSI driver supports.
Query the plugin's ControllerGetCapabilities / node capability output (or driver docs) to confirm which mount flags it advertises.
Upgrade (or pin) the CSI plugin to a version that supports the requested mount flags.
Check plugin allocation logs: the exact flag is deliberately hidden here, so verify flags via driver-side debugging.

Example fix

// before (job HCL)
volume "data" {
  type = "csi"
  mount_options {
    mount_flags = ["ro", "nfsvers=4.2"]
  }
}
// after: only flags the driver supports
volume "data" {
  type = "csi"
  mount_options {
    mount_flags = ["ro"]
  }
}

Defensive patterns

Strategy: validation

Validate before calling

func validateMountFlags(requested, advertised []string) error {
  supported := map[string]bool{}
  for _, f := range advertised { supported[f] = true }
  for _, f := range requested {
    if !supported[f] {
      return fmt.Errorf("mount flag %q not supported by plugin", f)
    }
  }
  return nil
}
// call with the plugin's advertised capabilities before issuing the volume claim

Type guard

func hasMountFlags(cap *csipbv1.VolumeCapability, want []string) bool {
  m := cap.GetMount()
  if m == nil { return false }
  for _, f := range want {
    if !slices.Contains(m.MountFlags, f) { return false }
  }
  return true
}

Try / catch

if err := compareCapabilities(expected, got); err != nil {
  for _, sub := range err.Errors {
    if strings.Contains(sub.Error(), "mount flags did not match") {
      log.Printf("job requests unsupported mount options: %v", sub)
    }
  }
}

Prevention

Keep job mount_options limited to flags documented by your CSI driver.
Pin and test the plugin version together with job volume specs.
Run ControllerValidateCapabilities in CI against real job volume definitions.
Remember exact flags are not logged (sensitive data) — audit job specs directly when this fires.

When it happens

Trigger: Calling ControllerValidateCapabilities where expectedMount.MountFlags contains a flag (from the job's mount_options / volume mount config) that the controller plugin's returned VolumeCapability.MountFlags does not include, causing the slices.Contains check at client.go:615 to fail for every candidate capability.

Common situations: Job file specifies mount_options (e.g. 'ro', 'nfsvers=4.1') unsupported by the CSI driver; driver version change dropped support for an option; driver returns UNKNOWN/partial capabilities; typo'd or driver-incompatible mount flag in host volume config.

Related errors

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