{"record":{"id":"d8c6148e641d6bf2","repo":"hashicorp/nomad","slug":"volume-mount-d-references-undefined-volume-s","errorCode":null,"errorMessage":"Volume Mount (%d) references undefined volume %s","messagePattern":"Volume Mount \\((.+?)\\) references undefined volume (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/structs.go","lineNumber":8398,"sourceCode":"\t\t// This task is a Connect proxy so it should not have service blocks\n\t\tif len(t.Services) > 0 {\n\t\t\tmErr.Errors = append(mErr.Errors, fmt.Errorf(\"Connect proxy task must not have a service block\"))\n\t\t}\n\t\tif t.Leader {\n\t\t\tmErr.Errors = append(mErr.Errors, fmt.Errorf(\"Connect proxy task must not have leader set\"))\n\t\t}\n\n\t\t// Ensure the proxy task has a corresponding service entry\n\t\tserviceErr := ValidateConnectProxyService(t.Kind.Value(), tg.Services)\n\t\tif serviceErr != nil {\n\t\t\tmErr.Errors = append(mErr.Errors, serviceErr)\n\t\t}\n\t}\n\n\t// Validation for volumes\n\tfor idx, vm := range t.VolumeMounts {\n\t\tif _, ok := tg.Volumes[vm.Volume]; !ok {\n\t\t\tmErr.Errors = append(mErr.Errors, fmt.Errorf(\"Volume Mount (%d) references undefined volume %s\", idx, vm.Volume))\n\t\t}\n\n\t\tif err := vm.Validate(); err != nil {\n\t\t\tmErr.Errors = append(mErr.Errors, fmt.Errorf(\"Volume Mount (%d) is invalid: \\\"%w\\\"\", idx, err))\n\t\t}\n\t}\n\n\t// Validate CSI Plugin Config\n\tif t.CSIPluginConfig != nil {\n\t\tif t.CSIPluginConfig.ID == \"\" {\n\t\t\tmErr.Errors = append(mErr.Errors, fmt.Errorf(\"CSIPluginConfig must have a non-empty PluginID\"))\n\t\t}\n\n\t\tif !CSIPluginTypeIsValid(t.CSIPluginConfig.Type) {\n\t\t\tmErr.Errors = append(mErr.Errors, fmt.Errorf(\"CSIPluginConfig PluginType must be one of 'node', 'controller', or 'monolith', got: \\\"%s\\\"\", t.CSIPluginConfig.Type))\n\t\t}\n\n\t\tif t.CSIPluginConfig.StagePublishBaseDir != \"\" && t.CSIPluginConfig.MountDir != \"\" &&","sourceCodeStart":8380,"sourceCodeEnd":8416,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/structs.go#L8380-L8416","documentation":"Task.Validate checks every `volume_mount` against the group's declared `volume` stanzas and emits \"Volume Mount (%d) references undefined volume %s\" when the mounted name is not defined at group level. Volumes must be declared on the group and referenced by name from tasks.","triggerScenarios":"A task has `volume_mount { volume = \"data\" }` but the group has no `volume \"data\"` stanza, or the names differ (typo/case).","commonSituations":"Renaming a group volume without updating task mounts; moving a task between groups that lack the volume; host_volume/CSI name mismatches after migration to the volume stanza syntax.","solutions":["Add a matching `volume` block on the group with the referenced name","Fix the volume name in the task's volume_mount to match the group declaration","Run `nomad job validate` to list all undefined volume references"],"exampleFix":"// before\ngroup \"app\" {\n  task \"srv\" {\n    volume_mount {\n      volume      = \"data\"\n      destination = \"/data\"\n    }\n  }\n}\n// after\ngroup \"app\" {\n  volume \"data\" {\n    type            = \"host\"\n    source          = \"data-vol\"\n  }\n  task \"srv\" {\n    volume_mount {\n      volume      = \"data\"\n      destination = \"/data\"\n    }\n  }\n}","handlingStrategy":"validation","validationCode":"for _, vm := range task.VolumeMounts {\n    if _, ok := group.Volumes[vm.Volume]; !ok {\n        return fmt.Errorf(\"task %q mounts undefined volume %q\", task.Name, vm.Volume)\n    }\n}","typeGuard":"func volumeDefined(g *structs.TaskGroup, name string) bool { _, ok := g.Volumes[name]; return ok }","tryCatchPattern":"if err := job.Validate(); err != nil {\n    if strings.Contains(err.Error(), \"references undefined volume\") { /* declare or fix volume name */ }\n}","preventionTips":["Declare group volumes before wiring task mounts","Keep volume names in shared constants when generating jobs","Run `nomad job validate` in CI for every spec change"],"tags":["nomad","volume","csi","job-validation"],"backgroundTag":"undefined-volume-reference","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"}