You’ve just run First Aid in Disk Utility, or fsck_apfs, and that reports warnings or errors. What should you do next?

Failure to unmount

By far the most frequent error encountered in Disk Utility’s checks results from its inability to unmount a volume before it can start testing. While this is reported as an error, and it prevents the checks from running, it can sometimes be solved by manually unmounting the volume in question. It normally doesn’t indicate anything sinister, and is simply frustrating.

Repeat in Recovery mode

If the warnings or errors were reported on your current boot Data volume and you ran that check in normal user mode, consider starting your Mac up in Recovery mode to repeat the check there.

Although macOS does an impressive job of performing checks on a live volume, it’s more reliable and more likely to be able to perform any repairs needed in Recovery mode, when the Data volume isn’t mounted and live. When there, if you prefer, you can still use fsck_apfs in Terminal.

The other case where checks may be best made in Recovery are those on an active Time Machine backup volume. That’s because those can be difficult to unmount before running the checks, although that is possible as long as a backup isn’t being made at the time, or Spotlight indexing taking place. The sure way to avoid those is to do so in Recovery mode.

Warnings or errors?

Any remarks about problems or irregularities encountered during checks should make explicit whether they are warnings or errors, and it’s essential to make a clear distinction between them.

Warnings are observations that could have significance, or might be perfectly normal in the circumstances. Only an APFS engineer is likely to be able to tell the difference. Among the commonest are those reporting missing xattrs for compressed files:
warning: inode (id 113812826): Resource Fork xattr is missing for compressed file
Experience is that those aren’t related to any consequent errors, and you should be able to leave those alone.

Errors are abnormalities that do have more significance, and might have the potential to cause further problems. Where possible, First Aid or fsck_apfs should attempt to repair those, most probably by performing “deferred repairs”. Those are normally minor errors that it already has plans to attend to when that volume is next mounted, the time that APFS normally performs its routine maintenance.

Snapshots

These are read-only copies of the file system metadata at a previous instant in time, and are associated with retained storage blocks. They aren’t part of the active volume, and their metadata are separate. As they’re read-only, any warnings or errors are most unlikely to be fixed, so you have a choice of leaving that snapshot to be deleted routinely by age, or deleting it early yourself.

Snapshots are made by backup utilities including Time Machine, which are required by Apple to have a mechanism that will delete them automatically after a set period. In the case of Time Machine, that’s when the snapshot is over 24 hours old. Snapshots aren’t backups, but augment regular backups, and stand in for them when backup storage isn’t available. In general, there seems little point in deleting a snapshot early just because there’s a reported warning or error for it, as that won’t affect the health of the active volume.

Identifying faulty items

Warnings and errors related to specific files or directories are normally given with an item id, which should be their inode number. To go any further, you’ll need to convert that to a path and file/directory name. You should therefore copy and paste all reports into a separate file as reference. Resolving an inode to a path and item name is detailed in this article.

In many cases involving items that can be resolved to an existing path, the faulty item is in one of the hidden folders such as .Spotlight-V100 for Spotlight indexes, or .DocumentRevisions-V100 for the document version database. In the former, rebuilding Spotlight’s indexes may resolve the problem, but you’re unlikely to be able to do anything about the latter.

If the inode resolves to a regular file, deleting that can remove the problem, but when you try restoring that file from a backup you may discover the backup has the same problem. Getting to the bottom of a recurrent file system error might require the knowledge and skills of an Apple engineer. Consider reporting this using Feedback, as it should then help iron out any remaining bugs in APFS.

You should also consider whether your Mac might be running old third-party software that is causing recurrent errors. Normally, products should work at a higher level that isolates them from the file system itself, but there are some surprising exceptions. If you can identify a cause, please inform the developers of that software so that it can be fixed.

Old versions of APFS

One potentially dangerous practice occurs when an older version of APFS changes a newer file system. APFS back in High Sierra and Mojave knew nothing of boot volume groups, firmlinks, or many of the features of more modern versions of APFS. If you really must run different versions of macOS on the same Mac, or shared external storage, avoid such version conflicts, and never run an older version of Disk Utility or fsck_apfs on a newer APFS container or volume.