Troubleshooting APFS Replication

Printer-Friendly Version

Apple's APFS replicator is typically fast and flawless, but it does not handle some conditions with grace (or at all). CCC works to avoid as many of these ungraceful results as possible, but we have the following recommendations for the cases where Apple's APFS replicator flops.

CCC reported that the APFS replication failed

If your first backup attempt failed, try the following steps. If you have already tried these steps and the problem recurred, see the next section for additional advice.

  1. Restart your Mac
  2. Rule out general hardware problems, and verify that your destination device is attached directly to a USB or Thunderbolt port on your Mac (avoid hubs). Consider removing any potentially-conflicting hardware drivers.
  3. Open Disk Utility
  4. Choose Show All Devices from the View menu
  5. Select the parent device of your destination volume in Disk Utility's sidebar †
  6. Click the Erase button in the toolbar
  7. If you see a volume named "ASRDataVolume_xxx", select that volume and click the button in the toolbar to remove it.
  8. Back in CCC, reset the destination selection, then try running the task again

† If you have other volumes or partitions on your destination disk that you do not want to lose, do not erase the whole disk. Instead, select the destination volume in this step. Click the "Erase Volume Group" button if it is presented in the Erase Volume panel.

If APFS replication fails repeatedly

Apple's APFS replicator will fail if there are problems with your installation of macOS, filesystem corruption on the source, storage driver conflicts, problems with the hardware, or if there are any media read failures. In short, it's just not very tolerable of real-world conditions. CCC's file copier is battle-tested — we've built years of experience into it to handle all sorts of challenging conditions with grace. In cases where Apple's APFS replicator simply can't get the job done, we recommend that you use CCC's file copier to make a backup of your Mac's Data volume.

1. Create and maintain a data-only backup

A data-only backup is a complete backup of all of your data, settings, and applications. This backup will be suitable for migrating all of your applications, data, and settings to a fresh installation of Catalina should that ever be required. Creation of the backup alone is sufficient to protect your data, however this will not produce a bootable backup, nor will it address any problems with the source. See Creating a data-only backup for details on how to configure a data-only backup.

2. Install macOS onto your data-only backup to produce a bootable backup

Installing macOS onto your data-only backup will produce a complete, bootable backup of your system. If corruption on the startup disk eventually leads to a failure of that volume, then you would be able to boot your Mac from the backup and continue working from the backup, and you could also do a complete restore to the internal disk (e.g. after erasing or replacing it). See Installing macOS onto a data-only backup for detailed instructions on installing macOS onto your data-only backup.

3. Erase the source and restore from the backup

Disk Utility typically cannot fix filesystem damage on APFS-formatted volumes; in most cases, the only way to resolve APFS filesystem corruption is to erase the affected volume and restore it from a backup. Especially if filesystem corruption on your source volume is causing misbehavior of the system, you can boot your Mac from the backup volume, erase the internal disk and restore the backup. See How to restore from your backup for details instructions for restoring your backup.

Related documentation

I stopped the backup task and now my destination disk is completely unresponsive

Apple's APFS replicator does not gracefully handle the cancelling of a replication task. The destination volume is essentially corrupted, but ASR does not erase the volume to place it back into its pre-task condition. Further, the destination device is not only completely unresponsive, but even Disk Utility cannot load devices and volumes. This is scarier than it looks initially, there is fortunately a simple solution.

Solution: Physically detach the destination device from your Mac, then reattach it. If the destination is an internal device or cannot be easily detached, simply restart your computer. Then choose Disk Utility from CCC's Utilities menu and reformat the destination.

We reported this ungraceful result to Apple (FB7324207) in September 2019 and we are still awaiting a response.

CCC reported that my source or destination is reporting read/write errors

Apple's APFS replicator clones the source volume at a very low level. Rather than copying individual files, it copies the filesystem data structures directly. Because this utility is not examining files on an individual basis, it's not able to deal with media failure nor filesystem corruption in a graceful manner (FB7338920). When ASR encounters media failure or filesystem corruption, the cloning task will fail and the destination volume will be in a corrupted state. The presence of media errors makes it very unlikely that ASR will be able to complete the clone, so CCC will not use the ASR utility if the source or destination is reporting read/write errors.

Solution: We recommend that you make a data-only backup, then address the hardware concern that led to the read/write errors, then restore your data from the backup.

Related documentation