{"record":{"id":"ad4f6b642dccd627","repo":"hashicorp/nomad","slug":"could-not-place-volume-q-w","errorCode":null,"errorMessage":"could not place volume %q: %w","messagePattern":"could not place volume %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/host_volume_endpoint.go","lineNumber":253,"sourceCode":"\t}\n\texisting, err := v.validateVolumeUpdate(vol, snap)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// set zero values as needed, possibly from existing\n\tnow := time.Now()\n\tvol.CanonicalizeForCreate(existing, now)\n\n\t// make sure any namespaces, nodes, or pools actually exist\n\terr = v.validateVolumeForState(vol, snap)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"validating volume %q against state failed: %v\", vol.Name, err)\n\t}\n\n\t_, err = v.placeHostVolume(snap, vol)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"could not place volume %q: %w\", vol.Name, err)\n\t}\n\n\twarn, err := v.enforceEnterprisePolicy(\n\t\tsnap, vol, args.GetIdentity().GetACLToken(), args.PolicyOverride)\n\tif warn != nil {\n\t\treply.Warnings = warn.Error()\n\t}\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// serialize client RPC and raft write per volume ID\n\tindex, err := v.serializeCall(vol.ID, \"create\", func() (uint64, error) {\n\t\t// Attempt to create the volume on the client.\n\t\t//\n\t\t// NOTE: creating the volume on the client via the plugin can't be made\n\t\t// atomic with the registration, and creating the volume provides values\n\t\t// we want to write on the Volume in raft anyways.","sourceCodeStart":235,"sourceCodeEnd":271,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/host_volume_endpoint.go#L235-L271","documentation":"The Create RPC for host volumes validated the requested volume, but the internal placement step (placeHostVolume) failed to allocate a host volume ID / slot in the state snapshot. Nomad wraps the underlying placement error so the operator knows which volume could not be placed. This indicates the RPC got past ACL and validation but failed during state mutation.","triggerScenarios":"Calling the HostVolume.Create RPC (e.g. `nomad volume create` for CSI/host volumes or the corresponding API POST /v1/volumes/host) when v.placeHostVolume returns an error, such as a state-store write failure or ID collision.","commonSituations":"Raft/state store instability, leadership flapping during the request, a collision or constraint failure in placeHostVolume, or submitting a create while the cluster state is inconsistent.","solutions":["Inspect the wrapped %w cause in the error message to see the underlying placement failure.","Retry the create request once leader election / state store health is confirmed.","Verify the server logs around placeHostVolume for the concrete error.","Upgrade Nomad if this reproduces consistently on a known-buggy version."],"exampleFix":"// before\n_, err = v.placeHostVolume(snap, vol)\nif err != nil {\n\treturn fmt.Errorf(\"could not place volume %q: %w\", vol.Name, err)\n}\n// after: fix the root cause reported by the wrapped error, e.g. ensure\n// the volume name does not collide with an existing volume before retrying\nexisting, _ := snap.HostVolumeByName(nil, vol.Namespace, vol.Name)\nif existing != nil {\n\treturn fmt.Errorf(\"volume %q already exists; choose a new name\", vol.Name)\n}","handlingStrategy":"retry","validationCode":"snap, _, err := client.State().Snapshot(nil)\nif err != nil { return err }\n// ensure cluster is stable and the name is free before create","typeGuard":null,"tryCatchPattern":"err := api.CreateHostVolume(req)\nvar he *api.StatusError\nif errors.As(err, &he) && strings.Contains(he.Error(), \"could not place volume\") {\n    // inspect wrapped cause, back off, retry once after confirming leadership\n}","preventionTips":["Keep the state store/raft healthy before volume operations","Check server logs for the wrapped cause","Avoid concurrent creates of the same volume name","Retry with backoff during leader elections"],"tags":["nomad","host-volumes","state-store","rpc"],"backgroundTag":"volume-placement-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"}