hashicorp/nomad · warning

Error listing host volumes

Error message

Error listing host volumes

What it means

hostVolumeListError is a sentinel (non-fatal) error used by 'volume status' when the -type flag is unset. When listing host volumes fails, the command wraps the underlying error with this sentinel and continues to list CSI volumes instead of failing outright. Callers use errors.Is to distinguish 'could not list host volumes' from more serious errors.

Source

Thrown at command/volume_status_host.go:19

// Copyright IBM Corp. 2015, 2026
// SPDX-License-Identifier: BUSL-1.1

package command

import (
	"errors"
	"fmt"
	"sort"
	"strings"

	humanize "github.com/dustin/go-humanize"
	"github.com/hashicorp/nomad/api"
)

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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the wrapped cause after the sentinel (the second %w) to fix the underlying API/ACL problem
2. Grant the ACL token volume-related read capabilities
3. Use -type csi or -type host explicitly to skip the combined listing path if one backend is unsupported

Example fix

// before
if err != nil { return err }
// after
if err != nil {
    if errors.Is(err, hostVolumeListError) { /* continue to CSI listing */ } else { return err }
}

// no pre-call validation; ensure agent is reachable and token has volume read ACLs
_ = client.Agent().Self() // connectivity smoke test

func isHostVolumeListError(err error) bool { return errors.Is(err, hostVolumeListError) }

if err != nil {
    if errors.Is(err, hostVolumeListError) {
        // non-fatal: proceed to CSI listing
    } else {
        return err
    }
}

When it happens

Trigger: Running `nomad volume status` without an ID and without -type, where getHostVolumeByPrefix (the host volume List API call) fails; the error is wrapped as fmt.Errorf("%w: %w", hostVolumeListError, err). Also returned from hostVolumeStatus when a specific host volume was found but fetching its status failed for a reason other than list failure.

Common situations: Nomad agent without host volume support or unreachable volume plugin; ACL token lacking volume listing permissions; transient API errors during a combined host+CSI volume status listing.

Related errors

• ErrPluginNotExists
• DriverStatsNotImplemented
• A template must be supplied using '-template' when using go-
• Invalid value for "-out"; valid values are [go-template, hcl
• -node or -node-pool options can only be used when no ID is p

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