{"record":{"id":"6f1b2360903bcc8a","repo":"hashicorp/nomad","slug":"failed-to-validate-volume-s-err-w","errorCode":null,"errorMessage":"failed to validate volume %s, err: %w","messagePattern":"failed to validate volume (.+?), err: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/client.go","lineNumber":1665,"sourceCode":"\t\t\t\tTopology: &numalib.Topology{},\n\t\t\t}\n\t\t}\n\t}\n\tif node.ReservedResources == nil {\n\t\tnode.ReservedResources = &structs.NodeReservedResources{}\n\t}\n\tif node.Datacenter == \"\" {\n\t\tnode.Datacenter = \"dc1\"\n\t}\n\tif node.Name == \"\" {\n\t\tnode.Name, _ = os.Hostname()\n\t}\n\tnode.CgroupParent = newConfig.CgroupParent\n\tif node.HostVolumes == nil {\n\t\tnode.HostVolumes = make(map[string]*structs.ClientHostVolumeConfig, len(newConfig.HostVolumes))\n\t\tfor k, v := range newConfig.HostVolumes {\n\t\t\tif _, err := os.Stat(v.Path); err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to validate volume %s, err: %w\", v.Name, err)\n\t\t\t}\n\t\t\tnode.HostVolumes[k] = v.Copy()\n\t\t}\n\t}\n\tnode.GCVolumesOnNodeGC = newConfig.GCVolumesOnNodeGC\n\n\tif node.HostNetworks == nil {\n\t\tif l := len(newConfig.HostNetworks); l != 0 {\n\t\t\tnode.HostNetworks = make(map[string]*structs.ClientHostNetworkConfig, l)\n\t\t\tfor k, v := range newConfig.HostNetworks {\n\t\t\t\tnode.HostNetworks[k] = v.Copy()\n\t\t\t}\n\t\t}\n\t}\n\n\tif node.Name == \"\" {\n\t\tnode.Name = node.ID\n\t}","sourceCodeStart":1647,"sourceCodeEnd":1683,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/client.go#L1647-L1683","documentation":"During client setup, every configured host volume's Path is checked with os.Stat before being registered on the node. If the path does not exist or is inaccessible, setup fails with this error wrapping the os.Stat error. This catches misconfigured volumes early instead of failing tasks later.","triggerScenarios":"A host_volume block in the client config declares a host path that does not exist on disk, cannot be traversed (permission denied on a parent dir), or points at a broken symlink, so os.Stat(v.Path) fails.","commonSituations":"Config copied from another machine; volume path on a mount that is not mounted yet at agent start; typo in the path; running Nomad in a container without the host path bind-mounted.","solutions":["Read the wrapped os error (no such file / permission denied) to see which case applies","Create the directory on the host (e.g. sudo mkdir -p /srv/nomad-volumes/data) or correct the path in the client host_volume config","Fix mount/permission issues (mount the volume, chown/chmod) and restart the Nomad client","Remove or comment out the host_volume entry if it is not used on this node"],"exampleFix":"// before\nclient {\n  host_volume \"data\" {\n    path = \"/mnt/missing/nomad-data\"\n  }\n}\n// after\nsudo mkdir -p /mnt/nomad/nomad-data\n// then\nclient {\n  host_volume \"data\" {\n    path = \"/mnt/nomad/nomad-data\"\n  }\n}","handlingStrategy":"validation","validationCode":"for _, v := range cfg.Client.HostVolumes {\n\tif _, err := os.Stat(v.Path); err != nil {\n\t\treturn fmt.Errorf(\"host volume %q path %q invalid before agent start: %w\", v.Name, v.Path, err)\n\t}\n}","typeGuard":null,"tryCatchPattern":"if err := validateHostVolumes(cfg); err != nil {\n\tlogger.Warn(\"skipping invalid host volume\", \"err\", err)\n\t// remove entry and reload config instead of failing the agent\n}","preventionTips":["Provision volume directories with config management before the Nomad unit starts","Use systemd unit ordering (RequiresMountsFor=/path) for mounted volumes","Validate paths when templating configs for multiple machines","Bind-mount host paths into containers running Nomad"],"tags":["nomad-client","host-volumes","configuration"],"backgroundTag":"volume-path-not-found","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"}