hashicorp/nomad · error

could not detach from controller: %v

Error message

could not detach from controller: %v

What it means

Fires in controllerUnpublishVolume when the ClientCSI.ControllerDetachVolume RPC to the plugin's controller fails; Nomad could not tell the storage backend to detach, so the claim stays published and the volume cannot be freed.

Source

Thrown at nomad/csi_endpoint.go:970

			return fmt.Errorf("missing external node ID: %v", err)
		}
		claim.ExternalNodeID = externalNodeID
	}

	req := &cstructs.ClientCSIControllerDetachVolumeRequest{
		VolumeID:        vol.RemoteID(),
		ClientCSINodeID: claim.ExternalNodeID,
		Secrets:         vol.Secrets,
	}
	req.PluginID = vol.PluginID

	err = v.serializedControllerRPC(vol.PluginID, func() error {
		return v.srv.RPC("ClientCSI.ControllerDetachVolume", req,
			&cstructs.ClientCSIControllerDetachVolumeResponse{})
	})
	if err != nil {
		return fmt.Errorf("could not detach from controller: %v", err)
	}

	v.logger.Trace("controller detach complete", "vol", vol.ID)
	claim.State = structs.CSIVolumeClaimStateReadyToFree
	return v.checkpointClaim(vol, claim)
}

// lookupExternalNodeID gets the CSI plugin's ID for a node.  we look it up in
// the volume's claims first because it's possible the client has been stopped
// and GC'd by this point, so looking there is the last resort.
func (v *CSIVolume) lookupExternalNodeID(vol *structs.CSIVolume, claim *structs.CSIVolumeClaim) (string, error) {
	for _, rClaim := range vol.ReadClaims {
		if rClaim.NodeID == claim.NodeID && rClaim.ExternalNodeID != "" {
			return rClaim.ExternalNodeID, nil
		}
	}
	for _, wClaim := range vol.WriteClaims {
		if wClaim.NodeID == claim.NodeID && wClaim.ExternalNodeID != "" {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check the CSI plugin controller logs for the underlying failure
2. Ensure at least one controller instance of the plugin is healthy
3. Retry unpublish; the serialized controller RPC will re-attempt detach

When it happens

Trigger: Thrown at nomad/csi_endpoint.go:970 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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