{"id":"33d990d353a6c9c8","repo":"docker/cli","slug":"can-only-update-cluster-volumes","errorCode":null,"errorMessage":"can only update cluster volumes","messagePattern":"can only update cluster volumes","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/volume/update.go","lineNumber":55,"sourceCode":"\t_ = flags.SetAnnotation(\"availability\", \"swarm\", []string{\"manager\"})\n\n\treturn cmd\n}\n\nfunc runUpdate(ctx context.Context, dockerCli command.Cli, volumeID, availability string, flags *pflag.FlagSet) error {\n\t// TODO(dperny): For this earliest version, the only thing that can be\n\t// updated is Availability, which is necessary because to delete a cluster\n\t// volume, the availability must first be set to \"drain\"\n\n\tapiClient := dockerCli.Client()\n\n\tres, err := apiClient.VolumeInspect(ctx, volumeID, client.VolumeInspectOptions{})\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tif res.Volume.ClusterVolume == nil {\n\t\treturn errors.New(\"can only update cluster volumes\")\n\t}\n\n\tif flags.Changed(\"availability\") {\n\t\tres.Volume.ClusterVolume.Spec.Availability = volume.Availability(availability)\n\t}\n\t_, err = apiClient.VolumeUpdate(ctx, res.Volume.ClusterVolume.ID, client.VolumeUpdateOptions{\n\t\tVersion: res.Volume.ClusterVolume.Version,\n\t\tSpec:    &res.Volume.ClusterVolume.Spec,\n\t})\n\treturn err\n}\n","sourceCodeStart":37,"sourceCodeEnd":67,"githubUrl":"https://github.com/docker/cli/blob/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/volume/update.go#L37-L67","documentation":"Returned by `docker volume update` (runUpdate in cli/command/volume/update.go) when the inspected volume has no ClusterVolume field. Volume update only exists for Swarm cluster volumes (CSI-backed), where the only mutable field is availability — needed e.g. to set 'drain' before deletion. Regular local volumes are immutable after creation, so the command refuses them.","triggerScenarios":"`docker volume update <name> --availability=...` against a volume created with the default local driver, or any volume that VolumeInspect returns without a ClusterVolume section — including running the command on a daemon that is not part of a Swarm or on a non-manager node.","commonSituations":"Users trying to modify options of ordinary named volumes (there is no supported way; volumes must be recreated); confusing local volumes with CSI cluster volumes; running against a standalone Docker engine instead of a Swarm manager with a CSI plugin.","solutions":["Verify the volume is a cluster volume: `docker volume inspect <name>` and check for a ClusterVolume section","If you need to change a local volume's options, recreate it: `docker volume rm` then `docker volume create` with the new options (migrate data first)","If it should be a cluster volume, run the command against a Swarm manager and ensure the volume was created via a CSI driver with cluster volume support"],"exampleFix":"# before (local volume)\ndocker volume update mydata --availability=drain\n# after (recreate local volume, or target an actual cluster volume)\ndocker volume inspect mydata --format '{{.ClusterVolume}}'\ndocker volume update my-csi-vol --availability=drain","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker-cli","volume","swarm","cluster-volume","csi"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}