hashicorp/nomad · error · hostVolumeListError

%w: %w

Error message

%w: %w

What it means

hostVolumeStatus wraps failures from getHostVolumeByPrefix with hostVolumeListError (a sentinel) plus the cause, using Go's multi-%w pattern so callers can errors.Is against the sentinel. It means the List/Get-by-prefix lookup for host volumes failed at the API level.

Source

Thrown at command/volume_status_host.go:34

// hostVolumeListError is a non-fatal error for the 'volume status' command when
// used with the -type option unset, because we want to continue on to list CSI
// volumes
var hostVolumeListError = errors.New("Error listing host volumes")

func (c *VolumeStatusCommand) hostVolumeStatus(client *api.Client, id, nodeID, nodePool string, opts formatOpts) error {
	if id == "" {
		return c.hostVolumeList(client, nodeID, nodePool, opts)
	}
	if nodeID != "" || nodePool != "" {
		return errors.New("-node or -node-pool options can only be used when no ID is provided")
	}

	// get a host volume that matches the given prefix or a list of all matches
	// if an exact match is not found. note we can't use the shared getByPrefix
	// helper here because the List API doesn't match the required signature
	volStub, possible, err := getHostVolumeByPrefix(client, id, c.namespace)
	if err != nil {
		return fmt.Errorf("%w: %w", hostVolumeListError, err)
	}
	if len(possible) > 0 {
		out, err := formatHostVolumes(possible, opts)
		if err != nil {
			return fmt.Errorf("Error formatting: %w", err)
		}
		return fmt.Errorf("Prefix matched multiple host volumes\n\n%s", out)
	}

	vol, _, err := client.HostVolumes().Get(volStub.ID, nil)
	if err != nil {
		return fmt.Errorf("Error querying host volume: %w", err)
	}

	str, err := formatHostVolume(vol, opts)
	if err != nil {
		return fmt.Errorf("Error formatting host volume: %w", err)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check the wrapped cause: 403 -> grant host volume read ACLs or fix NOMAD_NAMESPACE/NOMAD_REGION
2. Confirm cluster connectivity and that the server version supports host volumes
3. Match against the hostVolumeListError sentinel with errors.Is when handling programmatically

Example fix

// before
cmd := exec.Command("nomad", "volume", "status", "host", prefix) // can't distinguish list failure
// after
err := cmd.Run()
if err != nil && strings.Contains(errOut, "host volume list failed") { /* handle sentinel family */ }

// preflight ACL/connectivity
_, _, err := client.HostVolumes().List(nil)
if err != nil { return fmt.Errorf("host volumes unavailable: %w", err) }

var hostVolumeListError = errors.New("host volume list failed")
func isHostVolumeListError(err error) bool { return errors.Is(err, hostVolumeListError) }

if err := cmd.Run(); err != nil {
    if isHostVolumeListError(err) { /* API-level failure: check token/namespace/connectivity */ }
}

When it happens

Trigger: Run invokes hostVolumeStatus with an ID prefix; getHostVolumeByPrefix's List call fails — ACL denial, agent unreachable, namespace mismatch, or server RPC error.

Common situations: NOMAD_NAMESPACE set to a namespace the token cannot read; expired token; networking issue to the Nomad agent; server version predating the Host Volumes API.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• Error querying host volume: %w
• Error querying CSI plugins: %w
• Error listing host volumes
• Error formatting: %w
• Prefix matched multiple host volumes %s

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