hashicorp/nomad · error

unexpectedly did not forward Alloc.List to region %q

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.

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)

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.

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)
    }
}

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

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

• unexpectedly did not forward Job.List to region %q
• unexpectedly did not forward CSIVolume.List to region %q
• unexpectedly did not forward Variables.List to region %q
• No path to region
• controller list volumes: %v

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