hashicorp/nomad · error

volume existence check error: %v

Error message

volume existence check error: %v

What it means

While registering CSI volumes, the store checks whether the volume already exists with txn.First on the csi_volumes table. If that internal lookup returns an error (as opposed to just nil), registration is aborted with this wrapped error. It indicates a state store query failure, not a duplicate-volume condition (which is handled separately).

Source

Thrown at nomad/state/state_store.go:2661

	return iter, nil
}

// UpsertCSIVolume inserts a volume in the state store.
func (s *StateStore) UpsertCSIVolume(index uint64, volumes []*structs.CSIVolume) error {
	txn := s.db.WriteTxnMsgT(structs.CSIVolumeRegisterRequestType, index)
	defer txn.Abort()

	for _, v := range volumes {
		if exists, err := s.namespaceExists(txn, v.Namespace); err != nil {
			return err
		} else if !exists {
			return fmt.Errorf("volume %s is in nonexistent namespace %s", v.ID, v.Namespace)
		}

		obj, err := txn.First(TableCSIVolumes, "id", v.Namespace, v.ID)
		if err != nil {
			return fmt.Errorf("volume existence check error: %v", err)
		}
		if obj != nil {
			// Allow some properties of a volume to be updated in place, but
			// prevent accidentally overwriting important properties.
			old := obj.(*structs.CSIVolume)
			if old.ExternalID != v.ExternalID ||
				old.PluginID != v.PluginID ||
				old.Provider != v.Provider {
				return fmt.Errorf("volume identity cannot be updated: %s", v.ID)
			}
		} else {
			v.CreateIndex = index
		}
		v.ModifyIndex = index

		// Allocations are copy on write, so we want to keep the Allocation ID
		// but we need to clear the pointer so that we don't store it when we
		// write the volume to the state store. We'll get it from the db in

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check the wrapped %v underlying error
2. Retry the volume registration
3. If persistent, inspect server state store health and report to Nomad

_, err := client.CSIVolumes().Register(vol, nil, nil)
if err != nil && strings.Contains(err.Error(), "volume existence check error") {
  time.Sleep(backoff)
  return retry() // transient query failure, safe to retry
}

When it happens

Trigger: CSIVolumeRegister/CSIVolumeCreate path where txn.First(TableCSIVolumes, "id", namespace, id) errors during existence checking.

Common situations: Rare memdb/txn failures on servers; usually transient and seen in server logs during volume registration.

Related errors

• error parsing: root should be an object
• cannot specify Accessor ID
• volume clone ID cannot be updated
• volume snapshot ID cannot be updated
• volume requested capabilities update was not compatible with

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