Coping with errors caused by APFS filesystem corruption

This documentation is for an older version of CCC. You can find the latest version here.
Last updated on 27. April 2021

We regularly see cases of APFS filesystem corruption that lead to errors during a backup task. This corruption is typically presented in an error like one of these:

readlink_stat("/Photos/Foo/2020_Dumpster_fire.jpg") failed: Illegal byte sequence (92)
rename("/Photos/Foo/.2020_Dumpster_fire_out_of_control.jpg.asdfgh" -> "/Photos/Foo/2020_Dumpster_fire_out_of_control.jpg") failed: No such file or directory (2)

When CCC encounters these errors, the affected items are listed in CCC's Task History window, often with this advice:

When an error occurs while trying to read or modify a file or folder's filesystem attributes (e.g. ownership and permissions, modification date, file name, what folder it's in, etc.), that usually suggests that there is some corruption in that item's filesystem entry. The file may need to be deleted and, if applicable, restored from a backup.

In both of the error cases in the above example, the file or the parent folder is corrupted, and the APFS filesystem will not allow any modifications to those items. Sometimes you can simply delete the affected items, but sometimes this is not possible because the Finder does not reveal these corrupted items to you (because they are corrupted). Typically Disk Utility does not even detect this filesystem corruption, and it will never repair the corruption if doing so would require the removal of files or folders. Sadly, lacking any other utilities to repair the damage, your only remaining option for resolving the corruption is to erase the affected volume.

The folder swap method

If you are unable to see a corrupted item in the Finder (and therefore unable to delete it to resolve the corruption), there is one alternative that you may be able to consider. Often when errors are encountered while trying to make changes to a file (especially its name or location), the corruption is affecting the parent folder, not the file itself. In those cases you can replace the folder to remove the corruption. Supposing CCC is reporting errors on a file at "My Media Volume" > Photos > Foo > 2020_Dumpster_fire.jpg, you could do the following to replace the folder while retaining the bulk of its content:

  1. If the item you're looking for resides in a hidden folder (e.g. "/Users/yourname/Library"), you can press Command+Shift+Period to toggle the Finder's display of hidden items
  2. Navigate in the Finder to "My Media Volume" > Photos
  3. Create a new folder here named "Foo new"
  4. Select all of the items in "Foo" (e.g. Command+A) and drag them into "Foo new"
  5. Move "Foo" to the Trash†
  6. Rename "Foo new" --> "Foo"

† This does not solve the corruption problem, rather it only cordons the corruption off to a separate (and disposable) folder. In most of these cases, you'll find that Finder cannot empty the Trash, claiming that the files are "in use". That's just the Finder's way of expressing that it can't cope with the corrupted content, and has no advice that would actually be helpful. If you are unable to empty the Trash, and you would rather not erase the affected volume to remove the corruption, then you can create a new folder on the affected volume, e.g. "Corrupted Items" and move the items from the Trash into that new folder. You can then exclude that folder from your backup task to avoid the errors that its content would cause.