hashicorp/nomad · error

ErrUnknownNode

ErrUnknownNode

Error message

%w %s

What it means

Fires in lookupExternalNodeID: neither the volume's write nor past claims contain an external node ID for the claiming node, and the node itself no longer exists in the state store (structs.ErrUnknownNode wraps the node ID).

Source

Thrown at nomad/csi_endpoint.go:1006

		if wClaim.NodeID == claim.NodeID && wClaim.ExternalNodeID != "" {
			return wClaim.ExternalNodeID, nil
		}
	}
	for _, pClaim := range vol.PastClaims {
		if pClaim.NodeID == claim.NodeID && pClaim.ExternalNodeID != "" {
			return pClaim.ExternalNodeID, nil
		}
	}

	// fallback to looking up the node plugin
	ws := memdb.NewWatchSet()
	state := v.srv.fsm.State()
	targetNode, err := state.NodeByID(ws, claim.NodeID)
	if err != nil {
		return "", err
	}
	if targetNode == nil {
		return "", fmt.Errorf("%w %s", structs.ErrUnknownNode, claim.NodeID)
	}

	// get the storage provider's ID for the client node (not
	// Nomad's ID for the node)
	targetCSIInfo, ok := targetNode.CSINodePlugins[vol.PluginID]
	if !ok || targetCSIInfo.NodeInfo == nil {
		return "", fmt.Errorf("failed to find storage provider info for client %q, node plugin %q is not running or has not fingerprinted on this client", targetNode.ID, vol.PluginID)
	}
	return targetCSIInfo.NodeInfo.ID, nil
}

func (v *CSIVolume) checkpointClaim(vol *structs.CSIVolume, claim *structs.CSIVolumeClaim) error {
	v.logger.Trace("checkpointing claim")
	req := structs.CSIVolumeClaimRequest{
		VolumeID:     vol.ID,
		AllocationID: claim.AllocationID,
		NodeID:       claim.NodeID,
		Claim:        claim.Mode,

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the claiming client node is registered and not deregistered/purged
2. Re-run the client's node plugin so its ID can be fingerprinted
3. If the node is permanently gone, clean up the volume claim manually

When it happens

Trigger: Thrown at nomad/csi_endpoint.go:1006 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/4eec8b7702d6e21c. Report an issue: GitHub.