{"record":{"id":"674d19a20fa40504","repo":"hashicorp/nomad","slug":"validate-called-on-nil-host-volume-capability","errorCode":null,"errorMessage":"validate called on nil host volume capability","messagePattern":"validate called on nil host volume capability","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/host_volumes.go","lineNumber":319,"sourceCode":"\n// HostVolumeCapability is the requested attachment and access mode for a volume\ntype HostVolumeCapability struct {\n\tAttachmentMode VolumeAttachmentMode\n\tAccessMode     VolumeAccessMode\n}\n\nfunc (hvc *HostVolumeCapability) Copy() *HostVolumeCapability {\n\tif hvc == nil {\n\t\treturn nil\n\t}\n\n\tnhvc := *hvc\n\treturn &nhvc\n}\n\nfunc (hvc *HostVolumeCapability) Validate() error {\n\tif hvc == nil {\n\t\treturn errors.New(\"validate called on nil host volume capability\")\n\t}\n\n\tswitch hvc.AttachmentMode {\n\tcase HostVolumeAttachmentModeBlockDevice,\n\t\tHostVolumeAttachmentModeFilesystem:\n\tdefault:\n\t\treturn fmt.Errorf(\"invalid attachment mode: %q\", hvc.AttachmentMode)\n\t}\n\n\tswitch hvc.AccessMode {\n\tcase HostVolumeAccessModeSingleNodeReader,\n\t\tHostVolumeAccessModeSingleNodeWriter,\n\t\tHostVolumeAccessModeSingleNodeSingleWriter,\n\t\tHostVolumeAccessModeSingleNodeMultiWriter:\n\tdefault:\n\t\treturn fmt.Errorf(\"invalid access mode: %q\", hvc.AccessMode)\n\t}\n","sourceCodeStart":301,"sourceCodeEnd":337,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/host_volumes.go#L301-L337","documentation":"HostVolumeCapability.Validate is a value-receiver method, so it can be invoked on a nil *HostVolumeCapability. To fail safely rather than panic, it returns the sentinel 'validate called on nil host volume capability' when hvc == nil. It then validates the AttachmentMode enum.","triggerScenarios":"Calling Validate() on a nil *HostVolumeCapability pointer, e.g. a HostVolume whose Capabilities list or field was left nil, routed through validateVolumeUpdate or tests.","commonSituations":"Constructing HostVolume structs programmatically without initializing capabilities; JSON payloads omitting the capabilities field resulting in nil pointers; tests probing nil-safety of Validate.","solutions":["Initialize HostVolumeCapability before validation (non-nil pointer with a valid AttachmentMode)","Set attachment_mode to a valid value (block_device or filesystem) once non-nil","Guard call sites with a nil check before invoking Validate","If capabilities are optional, skip validating nil entries instead of passing them through"],"exampleFix":"// before\nvar cap *structs.HostVolumeCapability\ncap.Validate() // returns nil-capability error\n\n// after\ncap := &structs.HostVolumeCapability{\n  AttachmentMode: structs.HostVolumeAttachmentModeFilesystem,\n}\nif err := cap.Validate(); err != nil { /* handle */ }","handlingStrategy":"type-guard","validationCode":"if hvc == nil {\n\treturn errors.New(\"capability must be non-nil\")\n}\nswitch hvc.AttachmentMode {\ncase \"block_device\", \"filesystem\":\ndefault:\n\treturn fmt.Errorf(\"invalid attachment mode %q\", hvc.AttachmentMode)\n}","typeGuard":"func validHostVolumeCapability(hvc *structs.HostVolumeCapability) bool {\n\treturn hvc != nil &&\n\t\t(hvc.AttachmentMode == structs.HostVolumeAttachmentModeBlockDevice ||\n\t\t hvc.AttachmentMode == structs.HostVolumeAttachmentModeFilesystem)\n}","tryCatchPattern":null,"preventionTips":["Always initialize capability structs when building HostVolumes","Ensure JSON payloads include capabilities or treat them as optional at call sites","Run nil-safety tests around Validate calls"],"tags":["nomad","host-volume","nil-pointer","validation"],"backgroundTag":"nil-receiver-validation","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"}