hashicorp/nomad · error

unexpectedly did not forward Alloc.List to region

Error message

unexpectedly did not forward Alloc.List to region %q

What it means

namespaceTerminalAllocsInRegion forwards an Alloc.List RPC to a remote region to check for non-terminal allocations before a namespace delete. If the forward helper reports done=false — the RPC was never handled remotely — the code returns this internal error naming the region, aborting the delete path.

Solutions

  1. Confirm the remote region is alive and federated (nomad server members in that region).
  2. Check server logs for RPC/TLS/network errors toward that region.
  3. Remove stale region references from tooling or restore connectivity, then retry.
Defensive patterns

Strategy: retry

Validate before calling

for _, region := range regions {
    if _, _, err := client.Agent().MembersOpts(&api.QueryOptions{Region: region}); err != nil {
        return fmt.Errorf("region %s unreachable before alloc check: %w", region, err)
    }
}

Try / catch

if err != nil && strings.Contains(err.Error(), "did not forward Alloc.List") {
    // check server logs / region health, restore federation, retry
}

Prevention

When it happens

Trigger: Namespace deletion in a multi-region setup where Alloc.List forwarding to a peer region fails; the remote region is down, deregistered from gossip, or the region name is wrong.

Common situations: Federated clusters where a region was decommissioned but cleanup still targets it; network partitions between datacenters; mistyped region names in tooling.

Related errors


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

Appendix: source

Thrown at nomad/namespace_endpoint.go:359

	return true, nil
}

// namespaceTerminalAllocsInRegion returns true if the namespace contains only
// terminal allocations in the given region.
func (n *Namespace) namespaceTerminalAllocsInRegion(authToken, namespace, region string) (bool, error) {
	allocReq := &structs.AllocListRequest{
		QueryOptions: structs.QueryOptions{
			Region:     region,
			Namespace:  namespace,
			AllowStale: false,
			AuthToken:  authToken,
		},
	}

	var allocResp structs.AllocListResponse
	done, err := n.srv.forward("Alloc.List", allocReq, allocReq, &allocResp)
	if !done {
		return false, fmt.Errorf("unexpectedly did not forward Alloc.List to region %q", region)
	} else if err != nil {
		return false, err
	}

	for _, alloc := range allocResp.Allocations {
		if !alloc.ClientTerminalStatus() {
			return false, nil
		}
	}
	return true, nil
}

// namespaceNoAssociatedVolumesInRegion returns true if there are no volumes
// associated with the namespace in the given region.
func (n *Namespace) namespaceNoAssociatedVolumesInRegion(authToken, namespace, region string) (bool, error) {
	volumesReq := &structs.CSIVolumeListRequest{
		QueryOptions: structs.QueryOptions{
			Region:     region,

View on GitHub (pinned to 482b49bf1a)