{"record":{"id":"dc12248012d4e350","repo":"hashicorp/nomad","slug":"error-listing-host-volumes","errorCode":null,"errorMessage":"Error listing host volumes","messagePattern":"Error listing host volumes","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"command/volume_status_host.go","lineNumber":19,"sourceCode":"// Copyright IBM Corp. 2015, 2026\n// SPDX-License-Identifier: BUSL-1.1\n\npackage command\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"sort\"\n\t\"strings\"\n\n\thumanize \"github.com/dustin/go-humanize\"\n\t\"github.com/hashicorp/nomad/api\"\n)\n\n// 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)","sourceCodeStart":1,"sourceCodeEnd":37,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/volume_status_host.go#L1-L37","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the wrapped cause after the sentinel (the second %w) to fix the underlying API/ACL problem","Grant the ACL token volume-related read capabilities","Use -type csi or -type host explicitly to skip the combined listing path if one backend is unsupported"],"exampleFix":"// before\nif err != nil { return err }\n// after\nif err != nil {\n    if errors.Is(err, hostVolumeListError) { /* continue to CSI listing */ } else { return err }\n}","handlingStrategy":"type-guard","validationCode":"// no pre-call validation; ensure agent is reachable and token has volume read ACLs\n_ = client.Agent().Self() // connectivity smoke test","typeGuard":"func isHostVolumeListError(err error) bool { return errors.Is(err, hostVolumeListError) }","tryCatchPattern":"if err != nil {\n    if errors.Is(err, hostVolumeListError) {\n        // non-fatal: proceed to CSI listing\n    } else {\n        return err\n    }\n}","preventionTips":["Use errors.Is, not string comparison, when handling this error","Ensure ACL tokens include host volume read capabilities","Check agent/plugin health if host volume listings repeatedly fail"],"tags":["nomad","cli","host-volumes","sentinel-error"],"backgroundTag":"partial-listing-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"}