hashicorp/nomad · error · ErrUnknownAllocationPrefix

%s: %s

Error message

%s: %s

What it means

For claim requests where NodeID is not already set, Claim looks up the allocation by AllocationID to derive the node. If the allocation does not exist, it fails with ErrUnknownAllocationPrefix plus the allocation ID.

Source

Thrown at nomad/csi_endpoint.go:488

	if args.VolumeID == "" {
		return fmt.Errorf("missing volume ID")
	}

	isNewClaim := args.Claim != structs.CSIVolumeClaimGC &&
		args.State == structs.CSIVolumeClaimStateTaken
	// COMPAT(1.0): the NodeID field was added after 0.11.0 and so we
	// need to ensure it's been populated during upgrades from 0.11.0
	// to later patch versions. Remove this block in 1.0
	if isNewClaim && args.NodeID == "" {
		state := v.srv.fsm.State()
		ws := memdb.NewWatchSet()
		alloc, err := state.AllocByID(ws, args.AllocationID)
		if err != nil {
			return err
		}
		if alloc == nil {
			return fmt.Errorf("%s: %s",
				structs.ErrUnknownAllocationPrefix, args.AllocationID)
		}
		args.NodeID = alloc.NodeID
	}

	_, index, err := v.srv.raftApply(structs.CSIVolumeClaimRequestType, args)
	if err != nil {
		v.logger.Error("csi raft apply failed", "error", err, "method", "claim")
		return err
	}

	if isNewClaim {
		// if this is a new claim, add a Volume and PublishContext from the
		// controller (if any) to the reply
		err = v.controllerPublishVolume(args, reply)
		if err != nil {
			return fmt.Errorf("controller publish: %v", err)
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the allocation ID with nomad alloc status <id> and use a live alloc
2. Ensure NodeID is set in the claim request so lookup can be skipped
3. Re-run the job to create a fresh allocation before claiming the volume

Example fix

// before
req := structs.CSIVolumeClaimRequest{AllocationID: "bad-id", VolumeID: volID}
// after
req := structs.CSIVolumeClaimRequest{AllocationID: liveAllocID, VolumeID: volID, NodeID: nodeID}

alloc, _, err := client.Allocations().Info(allocID, nil)
if err != nil || alloc == nil {
    return fmt.Errorf("allocation %s not found", allocID)
}

func allocExists(a *api.Allocation) bool { return a != nil && a.ID != "" }

if err != nil && strings.Contains(err.Error(), structs.ErrUnknownAllocationPrefix) { fetch a live alloc and retry }

When it happens

Trigger: Claiming a CSI volume with an AllocationID that is absent from state store (alloc GCed, wrong ID, or alloc never created), while args.NodeID is empty.

Common situations: Referencing an allocation from a completed/GCed job; typo'd alloc ID in manual API calls; race where alloc is purged before volume claim; cluster restore losing allocs.

Related errors

• structs.ErrUnknownAllocationPrefix
• error parsing: root should be an object
• missing policy name
• cannot specify Accessor ID
• missing accessor ID

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