{"record":{"id":"cd81a8645b7e558d","repo":"hashicorp/nomad","slug":"volume-name-cannot-be-updated","errorCode":null,"errorMessage":"volume name cannot be updated","messagePattern":"volume name cannot be updated","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/csi.go","lineNumber":790,"sourceCode":"\t}\n\treturn nil\n}\n\n// Merge updates the mutable fields of a volume with those from\n// another volume. CSIVolume has many user-defined fields which are\n// immutable once set, and many fields that are not\n// user-settable. Merge will return an error if we try to mutate the\n// user-defined immutable fields after they're set, but silently\n// ignore fields that are controlled by Nomad.\nfunc (v *CSIVolume) Merge(other *CSIVolume) error {\n\tif other == nil {\n\t\treturn nil\n\t}\n\n\tvar errs *multierror.Error\n\n\tif v.Name != other.Name && other.Name != \"\" {\n\t\terrs = multierror.Append(errs, errors.New(\"volume name cannot be updated\"))\n\t}\n\tif v.ExternalID != other.ExternalID && other.ExternalID != \"\" {\n\t\terrs = multierror.Append(errs, errors.New(\n\t\t\t\"volume external ID cannot be updated\"))\n\t}\n\tif v.PluginID != other.PluginID {\n\t\terrs = multierror.Append(errs, errors.New(\n\t\t\t\"volume plugin ID cannot be updated\"))\n\t}\n\tif v.CloneID != other.CloneID && other.CloneID != \"\" {\n\t\terrs = multierror.Append(errs, errors.New(\n\t\t\t\"volume clone ID cannot be updated\"))\n\t}\n\tif v.SnapshotID != other.SnapshotID && other.SnapshotID != \"\" {\n\t\terrs = multierror.Append(errs, errors.New(\n\t\t\t\"volume snapshot ID cannot be updated\"))\n\t}\n","sourceCodeStart":772,"sourceCodeEnd":808,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/csi.go#L772-L808","documentation":"This error comes from CSIVolume.Merge (nomad/structs/csi.go), which is used (e.g. by reconcileVolume) to apply updated volume claims onto an existing CSIVolume. Immutable identity fields of a volume — its Name, ExternalID, PluginID, CloneID — may not change once registered. When a proposed update carries a different, non-empty Name than the existing volume, Merge appends \"volume name cannot be updated\" to the returned multierror.","triggerScenarios":"Submitting a volume registration/update for a CSI volume ID whose spec has a different `name` than the previously registered volume (e.g. `nomad volume update`/register path, or a client reconcile of a volume claim where the stored volume's Name differs from the incoming one).","commonSituations":"Re-registering a volume after renaming it in the jobspec; copying a volume block from another job with a different name but the same volume ID; state drift after restoring volumes from a snapshot/backup.","solutions":["Keep the volume name identical to the existing registration, or deregister the volume (nomad volume deregister) and register it fresh under the new name.","Use a distinct volume ID for the renamed volume instead of reusing the old ID.","Diff the existing volume (nomad volume status <id>) against your spec to spot mismatched immutable fields before submitting."],"exampleFix":"// before\nvolume \"old-name\" {\n  type   = \"csi\"\n  id     = \"ebs-0\"  // previously registered as name \"ebs-0\" too\n  external_id = \"vol-123\"\n}\n\n// after: either keep the name\ncsi_volume \"ebs-0\" { ... }\n\n// or deregister then re-register with the new name\n// nomad volume deregister ebs-0\n// nomad volume register new.hcl","handlingStrategy":"validation","validationCode":"existing, _ := client.Volumes().Get(ctx, volID)\nif existing != nil && volSpec.Name != existing.Name {\n    return fmt.Errorf(\"volume %s: name is immutable; deregister before renaming\", volID)\n}","typeGuard":null,"tryCatchPattern":"if err := csiVolume.Merge(update); err != nil {\n    if strings.Contains(err.Error(), \"volume name cannot be updated\") {\n        return fmt.Errorf(\"keep the volume name or deregister and re-register\")\n    }\n    return err\n}","preventionTips":["Diff your volume spec against `nomad volume status <id>` before submitting updates.","Never rename a volume in place; deregister and register a new volume.","Use unique volume IDs per name to avoid reuse collisions."],"tags":["nomad","csi","storage","immutable-field"],"backgroundTag":"immutable-field-update","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"}