hashicorp/nomad · error

Error listing CSI volumes: %w

Error message

Error listing CSI volumes: %w

What it means

csiVolumeStatus first lists CSI volumes with a prefix search (client.CSIVolumes().List with Prefix). If the API list call returns an error (network failure, ACL denial, server error), it is wrapped as `Error listing CSI volumes`. This is a transport/API-level failure, not a parsing problem.

Source

Thrown at command/volume_status_csi.go:32

	multierror "github.com/hashicorp/go-multierror"
	"github.com/hashicorp/nomad/api"
)

func (c *VolumeStatusCommand) csiVolumeStatus(client *api.Client, id string, opts formatOpts) error {
	if id == "" {
		return c.csiVolumesList(client, opts)
	}

	// get a CSI volume that matches the given prefix or a list of all matches if an
	// exact match is not found.
	volStub, possible, err := getByPrefix[api.CSIVolumeListStub]("volumes", client.CSIVolumes().List,
		func(vol *api.CSIVolumeListStub, prefix string) bool { return vol.ID == prefix },
		&api.QueryOptions{
			Prefix:    id,
			Namespace: c.namespace,
		})
	if err != nil {
		return fmt.Errorf("Error listing CSI volumes: %w", err)
	}
	if len(possible) > 0 {
		out, err := csiFormatVolumes(possible, c.json, c.template)
		if err != nil {
			return fmt.Errorf("Error formatting: %w", err)
		}
		return fmt.Errorf("Prefix matched multiple CSI volumes\n\n%s", out)
	}

	// Try querying the volume
	vol, _, err := client.CSIVolumes().Info(volStub.ID, nil)
	if err != nil {
		return fmt.Errorf("Error querying CSI volume: %w", err)
	}

	str, err := c.formatCSIBasic(vol)
	if err != nil {
		return fmt.Errorf("Error formatting CSI volume: %w", err)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the wrapped cause (%w output) — fix connectivity (NOMAD_ADDR, agent health) or re-authenticate the ACL token.
2. Verify the token has list/read capabilities on volumes in the target namespace: `nomad acl token self`.
3. Check `nomad server members` / agent logs for server-side errors and retry once the cluster is healthy.

// pre-checks before calling
if os.Getenv("NOMAD_TOKEN") == "" && aclEnabled { return fmt.Errorf("NOMAD_TOKEN required") }
if _, err := net.DialTimeout("tcp", agentAddr, 2*time.Second); err != nil {
	return fmt.Errorf("nomad agent unreachable: %v", err)
}

vols, err := client.CSIVolumes().List(q)
if err != nil {
	var apiErr *api.APIError
	if errors.As(err, &apiErr) && apiErr.ErrCode() == 403 {
		return fmt.Errorf("token lacks volume list capability: %v", err)
	}
	return fmt.Errorf("Error listing CSI volumes: %w", err)
}

When it happens

Trigger: `nomad volume status <prefix>` when the Nomad API call for listing CSI volumes fails: unreachable agent, expired/insufficient ACL token lacking volume read (e.g. `volume` namespace capabilities), server-side 5xx.

Common situations: Wrong NOMAD_ADDR; ACL token without volume listing permissions; CSI plugin not running so the server errors; network partition between CLI and cluster.

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 CSI volume: %w
• Error querying CSI volumes: %w
• failed to send input: %w
• http addr of node %q (%s) is not advertised
• failed to derive Consul token for task %s: %v

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