{"record":{"id":"a601e3e2171d6cbb","repo":"hashicorp/nomad","slug":"w-w-a601e3","errorCode":null,"errorMessage":"%w: %w","messagePattern":"%w: %w","errorType":"console","errorClass":"hostVolumeListError","httpStatus":null,"severity":"error","filePath":"command/volume_status_host.go","lineNumber":34,"sourceCode":"// hostVolumeListError is a non-fatal error for the 'volume status' command when\n// used with the -type option unset, because we want to continue on to list CSI\n// volumes\nvar hostVolumeListError = errors.New(\"Error listing host volumes\")\n\nfunc (c *VolumeStatusCommand) hostVolumeStatus(client *api.Client, id, nodeID, nodePool string, opts formatOpts) error {\n\tif id == \"\" {\n\t\treturn c.hostVolumeList(client, nodeID, nodePool, opts)\n\t}\n\tif nodeID != \"\" || nodePool != \"\" {\n\t\treturn errors.New(\"-node or -node-pool options can only be used when no ID is provided\")\n\t}\n\n\t// get a host volume that matches the given prefix or a list of all matches\n\t// if an exact match is not found. note we can't use the shared getByPrefix\n\t// helper here because the List API doesn't match the required signature\n\tvolStub, possible, err := getHostVolumeByPrefix(client, id, c.namespace)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"%w: %w\", hostVolumeListError, err)\n\t}\n\tif len(possible) > 0 {\n\t\tout, err := formatHostVolumes(possible, opts)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"Error formatting: %w\", err)\n\t\t}\n\t\treturn fmt.Errorf(\"Prefix matched multiple host volumes\\n\\n%s\", out)\n\t}\n\n\tvol, _, err := client.HostVolumes().Get(volStub.ID, nil)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"Error querying host volume: %w\", err)\n\t}\n\n\tstr, err := formatHostVolume(vol, opts)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"Error formatting host volume: %w\", err)\n\t}","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/volume_status_host.go#L16-L52","documentation":"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.","triggerScenarios":"Run invokes hostVolumeStatus with an ID prefix; getHostVolumeByPrefix's List call fails — ACL denial, agent unreachable, namespace mismatch, or server RPC error.","commonSituations":"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.","solutions":["Check the wrapped cause: 403 -> grant host volume read ACLs or fix NOMAD_NAMESPACE/NOMAD_REGION","Confirm cluster connectivity and that the server version supports host volumes","Match against the hostVolumeListError sentinel with errors.Is when handling programmatically"],"exampleFix":"// before\ncmd := exec.Command(\"nomad\", \"volume\", \"status\", \"host\", prefix) // can't distinguish list failure\n// after\nerr := cmd.Run()\nif err != nil && strings.Contains(errOut, \"host volume list failed\") { /* handle sentinel family */ }","handlingStrategy":"try-catch","validationCode":"// preflight ACL/connectivity\n_, _, err := client.HostVolumes().List(nil)\nif err != nil { return fmt.Errorf(\"host volumes unavailable: %w\", err) }","typeGuard":"var hostVolumeListError = errors.New(\"host volume list failed\")\nfunc isHostVolumeListError(err error) bool { return errors.Is(err, hostVolumeListError) }","tryCatchPattern":"if err := cmd.Run(); err != nil {\n    if isHostVolumeListError(err) { /* API-level failure: check token/namespace/connectivity */ }\n}","preventionTips":["Ensure token has host-volume read ACLs in NOMAD_NAMESPACE","Confirm server version supports host volumes","Use errors.Is against hostVolumeListError for programmatic handling"],"tags":["cli","api","acl","host-volumes"],"backgroundTag":"api-request-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}