hoakley Macs, Technology

How can you rebuild or repair an APFS Volume Group?

There’s one big snag with Catalina’s ingenious linkage of System and Data volumes into a Volume Group: when anything goes wrong, the only option seems to be to wipe them both and start again. I’ve heard of a steady succession of users who’ve been caught by this, most commonly when trying to re-install earlier releases of Catalina.

What typically happens is that multiple Data volumes are created, such as both Macintosh HD – Data and Macintosh HD – Data – Data. The Volume Group may then be formed from the System volume and its duplicated Data volume, which isn’t the one the user wants. Ordinarily, this isn’t a big deal as you’re performing a clean re-install and there’s nothing significant on either Data volume. But what if you want to preserve what’s on your original Data volume and make that part of the Volume Group instead of the duplicate?

Unfortunately, Apple’s reference documentation on APFS doesn’t give any clear account of Catalina’s boot Volume Group, nor of the firmlinks which bind the System and Data volumes together. Reading between the lines, the following key steps are performed by the macOS Installer when it creates a new Volume Group:

  • both volumes are assigned their roles, S (System) and D (Data);
  • a unique Volume Group UUID is saved to them both;
  • the firmlinks on both volumes are set to refer to one another, as they’re bidirectional.

Needless to say, even the Recovery edition of Disk Utility doesn’t appear to have any commands or tools to support forming or dissolving a Volume Group.

Commands for working with APFS and its features are part of the general diskutil command. Although that does offer some scope for working with Volume Groups, that’s currently extremely limited. The only verbs or subcommands which are specific to Volume Groups at present are:

  • listVolumeGroups, which lists all current Volume Groups, and
  • changeVolumeRole, which changes the role of a volume.

The latter command doesn’t appear able to perform the other two (or more?) tasks required to make a boot Volume Group. Instead, diskutil apfs appears geared up to setting up Volume Groups when creating and adding a new volume with the -groupWith option, which isn’t what we need.

Listing Volume Groups gives an idea of how they are used:
+-- Container disk5 5BA1AAC8-3AD4-4594-AF01-7C0AA75CABAD
| |
| +-> Volume Group 68627CBB-D774-444E-97C6-F9511B5030F3
| =================================================
| APFS Volume Disk (Role): disk5s1 (Data)
| Name: Macintosh HD - Data
| Volume UUID: 68627CBB-D774-444E-97C6-F9511B5030F3
| Capacity Consumed: 580769214464 B (580.8 GB)
| -------------------------------------------------
| APFS Volume Disk (Role): disk5s5 (System)
| Name: Macintosh HD
| Volume UUID: 8B9FF440-75C8-4F7F-B09E-9222D44A2276
| Capacity Consumed: 11239186432 B (11.2 GB)

For each volume in the group, there’s a role, which we can change using
diskutil apfs changeVolumeRole disk5s1 D
which turns the volume at disk5s1 into a Data volume, but that doesn’t assign it a Volume Group here using the UUID of 68627CBB-D774-444E-97C6-F9511B5030F3. You can use changeVolumeRole to remove a volume from a group, using the lower case for the role, or the character zero 0. So
diskutil apfs changeVolumeRole disk5s1 d
would split that volume from a Volume Group, and it would cease to have the role of a Data volume.

Unless there’s a way to remove a newly created Data volume from a Volume Group, and add an existing volume to that group in the role of Data volume, the best solution that I can think of runs as follows:

  1. Boot the Mac from a different startup disk.
  2. Clone the contents of your existing Data volume to a different volume using Carbon Copy Cloner or similar.
  3. Perform a clean re-install, with the Installer creating new System and Data volumes in a Volume Group.
  4. Restart from your different startup disk.
  5. Clone the original Data volume back to the newly created Data volume.

A similar sequence would be required to perform other similar repairs to the boot Volume Group.

Apple doesn’t provide a full suite of maintenance and repair tools for APFS and its volumes. Third-parties have been prevented from doing so because Apple has still not provided documentation more than a year after developers first started using macOS Catalina. All this changes again with the arrival of Big Sur and its Sealed System Volume, where the contents of the system are contain in a special snapshot which is cryptographically sealed and mounted read-only. I can see a lot of users having to perform repeated clean re-installs of macOS 11.0 because there are simply no other options.