docker/cli · error

can only update cluster volumes

Error message

can only update cluster volumes

What it means

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.

Source

Thrown at cli/command/volume/update.go:55

	_ = flags.SetAnnotation("availability", "swarm", []string{"manager"})

	return cmd
}

func runUpdate(ctx context.Context, dockerCli command.Cli, volumeID, availability string, flags *pflag.FlagSet) error {
	// TODO(dperny): For this earliest version, the only thing that can be
	// updated is Availability, which is necessary because to delete a cluster
	// volume, the availability must first be set to "drain"

	apiClient := dockerCli.Client()

	res, err := apiClient.VolumeInspect(ctx, volumeID, client.VolumeInspectOptions{})
	if err != nil {
		return err
	}

	if res.Volume.ClusterVolume == nil {
		return errors.New("can only update cluster volumes")
	}

	if flags.Changed("availability") {
		res.Volume.ClusterVolume.Spec.Availability = volume.Availability(availability)
	}
	_, err = apiClient.VolumeUpdate(ctx, res.Volume.ClusterVolume.ID, client.VolumeUpdateOptions{
		Version: res.Volume.ClusterVolume.Version,
		Spec:    &res.Volume.ClusterVolume.Spec,
	})
	return err
}

View on GitHub (pinned to e9452d6e78)

Solutions

1. Verify the volume is a cluster volume: `docker volume inspect <name>` and check for a ClusterVolume section
2. 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)
3. 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

Example fix

# before (local volume)
docker volume update mydata --availability=drain
# after (recreate local volume, or target an actual cluster volume)
docker volume inspect mydata --format '{{.ClusterVolume}}'
docker volume update my-csi-vol --availability=drain

When it happens

Trigger: `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.

Common situations: 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.

Related errors

• images options are incompatible with type volume
• cluster options are incompatible with type volume
• unsupported type
• when using secret driver secret data must be empty
• error reading from STDIN: data is empty

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/33d990d353a6c9c8.json. Report an issue: GitHub.