{"record":{"id":"ac64e857654f59cd","repo":"hashicorp/nomad","slug":"volume-validation-failed-w","errorCode":null,"errorMessage":"volume validation failed: %w","messagePattern":"volume validation failed: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/host_volume_endpoint.go","lineNumber":419,"sourceCode":"\t\t}\n\t\treturn idx, nil\n\t})\n\tif err != nil {\n\t\treturn err\n\t}\n\n\treply.Volume = vol\n\treply.Index = index\n\treturn nil\n}\n\nfunc (v *HostVolume) validateVolumeUpdate(\n\tvol *structs.HostVolume, snap *state.StateSnapshot) (*structs.HostVolume, error) {\n\n\t// validate the volume spec\n\terr := vol.Validate()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"volume validation failed: %w\", err)\n\t}\n\n\tns, err := snap.NamespaceByName(nil, vol.Namespace)\n\tif err != nil {\n\t\treturn nil, err // should never hit, bail out\n\t}\n\tif ns == nil {\n\t\treturn nil, fmt.Errorf(\"volume validation failed: no such namespace %q\", vol.Namespace)\n\t}\n\n\t// validate any update we're making\n\tvar existing *structs.HostVolume\n\tif vol.ID != \"\" {\n\t\texisting, err = snap.HostVolumeByID(nil, vol.Namespace, vol.ID, true)\n\t\tif err != nil {\n\t\t\treturn nil, err // should never hit, bail out\n\t\t}\n\t\tif existing == nil {","sourceCodeStart":401,"sourceCodeEnd":437,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/host_volume_endpoint.go#L401-L437","documentation":"validateVolumeUpdate (shared by Create and Register) first runs vol.Validate() against the submitted volume spec. A structurally invalid volume (missing required fields, invalid values) is rejected with this wrapped error. The wrapped cause describes exactly which field failed validation.","triggerScenarios":"Submitting a HostVolume via Create or Register whose spec fails structs.HostVolume.Validate — e.g. missing HostPath/NodeID fields, invalid characters in the name, or out-of-range values.","commonSituations":"Hand-written HCL/JSON volume definitions with typos; automation generating specs with empty required fields; schema changes between Nomad versions making previously valid specs invalid.","solutions":["Read the wrapped %w error to identify the offending field.","Fix the volume spec per the Nomad host volume documentation (required fields, name constraints).","Run client-side validation of the HCL/JSON before submitting.","Check the Nomad version's schema if specs were valid on an older version."],"exampleFix":"// before\nvolume {\n  name        = \"My Volume\"  // invalid characters/space\n  host_path   = \"/data\"\n}\n// after\nvolume {\n  name        = \"my-volume\"\n  type        = \"host\"\n  host_path   = \"/data\"\n}","handlingStrategy":"validation","validationCode":"if vol.Name == \"\" || vol.NodeID == \"\" && vol.HostPath == \"\" {\n    return errors.New(\"volume spec incomplete: name and host_path/node_id required\")\n}","typeGuard":"func validHostVolume(v *api.HostVolume) bool {\n    return v != nil && v.Name != \"\" && v.HostPath != \"\"\n}","tryCatchPattern":"if strings.Contains(err.Error(), \"volume validation failed\") {\n    // surface wrapped cause to the spec author; fix field values\n}","preventionTips":["Lint volume HCL/JSON before submission","Keep specs current with the Nomad version's schema","Use `nomad volume` CLI to pre-validate specs","Test specs in a dev cluster first"],"tags":["nomad","host-volumes","validation","schema"],"backgroundTag":"schema-validation-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"}