{"record":{"id":"44a3b02bc1adeeb7","repo":"hashicorp/nomad","slug":"missing-volume-definition-44a3b0","errorCode":null,"errorMessage":"missing volume definition","messagePattern":"missing volume definition","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/host_volume_endpoint.go","lineNumber":213,"sourceCode":"\tif !v.srv.peersCache.ServersMeetMinimumVersion(\n\t\tv.srv.Region(),\n\t\tminVersionDynamicHostVolumes,\n\t\tfalse,\n\t) {\n\t\treturn fmt.Errorf(\n\t\t\t\"all servers should be running version %v or later to use dynamic host volumes\",\n\t\t\tminVersionDynamicHostVolumes,\n\t\t)\n\t}\n\n\tallowVolume := acl.NamespaceValidator(acl.NamespaceCapabilityHostVolumeCreate)\n\taclObj, err := v.srv.ResolveACL(args)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tif args.Volume == nil {\n\t\treturn fmt.Errorf(\"missing volume definition\")\n\t}\n\n\tvol := args.Volume\n\tif vol.Namespace == \"\" {\n\t\tvol.Namespace = args.RequestNamespace()\n\t}\n\tif !allowVolume(aclObj, vol.Namespace) {\n\t\treturn structs.ErrPermissionDenied\n\t}\n\t// Check if override is set and we do not have permissions\n\tif args.PolicyOverride {\n\t\tif !aclObj.AllowNsOp(vol.Namespace, acl.NamespaceCapabilitySentinelOverride) {\n\t\t\treturn structs.ErrPermissionDenied\n\t\t}\n\t}\n\n\t// ensure we only try to create a valid volume or make valid updates to a\n\t// volume","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/host_volume_endpoint.go#L195-L231","documentation":"HostVolume.Create requires a volume definition embedded in the request (args.Volume). If the request specifies a target but carries no Volume object, the endpoint returns \"missing volume definition\". The RPC intentionally does not guess defaults; a fully-formed volume spec is mandatory.","triggerScenarios":"Sending a HostVolumeCreateRequest with nil/omitted Volume field — e.g. calling the raw RPC, an API client that serializes the body without the 'volume' key, or `nomad host volume create` given flags that fail to build a volume struct.","commonSituations":"Custom automation hitting the HTTP API with a JSON body missing the nested volume object, typos in the JSON field name (e.g. 'volumes' instead of 'volume'), or old tooling unaware of the required nested definition.","solutions":["Include a complete volume definition in the request: {\"volume\": {\"name\": \"...\", \"host_path\": \"...\", ...}}.","Check JSON key spelling and nesting when calling the HTTP API directly.","Prefer the official CLI/Go client (nomad host volume create) which constructs the Volume struct correctly.","Validate the payload against the api.HostVolume struct for your Nomad version."],"exampleFix":"// before: missing nested object\n{\"name\": \"web-vol\"}\n// after\n{\"volume\": {\"name\": \"web-vol\", \"type\": \"host\", \"requested_capabilities\": [{\"Capability\": \"mount\"}]}}","handlingStrategy":"validation","validationCode":"// validate payload before sending\nif req.Volume == nil || req.Volume.Name == \"\" || req.Volume.HostPath == \"\" {\n    return fmt.Errorf(\"request must embed a complete volume definition\")\n}","typeGuard":"func hasVolumeDef(req *api.HostVolumeCreateRequest) bool {\n    return req != nil && req.Volume != nil && req.Volume.Name != \"\"\n}","tryCatchPattern":"err := client.HostVolumes().Create(req, nil)\nif err != nil && strings.Contains(err.Error(), \"missing volume definition\") {\n    // fix payload: nested 'volume' object required\n}","preventionTips":["Use the official CLI/Go client to build requests","Validate JSON key spelling ('volume', not 'volumes') in direct HTTP calls","Unit-test API payloads against the api.HostVolume struct"],"tags":["nomad","host-volumes","request-validation"],"backgroundTag":"missing-required-argument","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"}