This article explains how to deal with warnings and errors reported either when you run Disk Utility’s First Aid, or by the command tools fsck or fsck_apfs, on an APFS volume or container.

Keep a record

Even if the item is repaired successfully, it’s essential to keep a record of what happened. In Disk Utility, expand the First Aid window so you can see the full output of fsck_apfs, select its whole contents, copy and paste them into a text document, and save that. Do the same with the output in Terminal if that’s what you used.

You may also find two text log files of potential use: /var/log/fsck_apfs.log and /var/log/fsck_apfs_error.log, both accessible in Console or a text editor. Although errors may also be written to the Unified log, you’ll probably want to avoid going there.

Was this on the Data volume?

First Aid in Disk Utility will check and attempt to repair the current Data volume when running in normal user mode, by effectively freezing the Mac. However, that’s not as reliable as running the same procedure when your Mac is in Recovery mode. If you see warnings or errors reported from the current Data volume in normal user mode, before going any further start your Mac up in Recovery and repeat the checks in Disk Utility (or fsck_apfs) there, to confirm they are real, and give your Mac the best chance of making a successful repair.

This can also sometimes help when checking backup volumes, and any that have proved difficult to check because the volume can’t be unmounted in normal user mode.

Are these just warnings?

Read carefully through your copy of the output of fsck_apfs and check whether the comments there are warnings, or contain specific errors. Warnings aren’t uncommon, and are often of little consequence even when you can understand them. Among the commonest is
Resource Fork xattr is missing for compressed file
As there’s nothing you could or should do about that, keep the record and don’t worry about it.

You’ll occasionally see a report that “deferred repairs” were completed. These appear to be minor fixes that APFS keeps for a convenient moment. Provided they are fixed without further error, you should be able to ignore them safely.

If a line explicitly reports an error, and fsck_apfs was unable to repair it, then it’s something you should take more seriously, and try to pin down the site of the problem.

Identify the item

fsck_apfs identifies items with their inode number, an integer that can be very large. To make any sense of that, you need the volume number as well, and a means of converting the two into a path. My free utility Mints can do that in its inode Resolver window, from the Window/Data/Inode menu command, or you can do it yourself in Terminal with a command like
GetFileInfo /.vol/[volnumber]/[inode]
where volnumber is the volume number, and inode is the number given in the error or warning. This is explained in detail here.

Now that you know which file or folder resulted in the error or warning, you need to decide whether you can do anything about it. This is most important when you keep seeing similar errors, so you can prevent them from happening in the first place.

Is the item in a snapshot?

Checking snapshot 2 of 23 (com.apple.TimeMachine.2023-08-27-072736.local)
warning: inode (id 113812826): Resource Fork xattr is missing for compressed file

Snapshots are a special case, as they’re intended to be read-only, so are most unlikely to be repairable. If this is a snapshot on a volume that is backed up by Time Machine or another utility, then the only way you’ll fix this is by deleting that snapshot. Don’t do that, though, if the snapshot is on the volume storing your backups, as you’d be deleting one of those backups.

If this problem recurs in other snapshots, then it most probably reflects a problem in the file in the snapshot. Is it perhaps a large virtual machine (VM) or something similar? Keep your VMs on a separate volume which you exclude from backups, because of the many problems they can cause. The best way to back up a VM is when it’s shut down, as a simple copy to a separate backup storage volume. You can do the same with any other file that seems to be the cause of repeated problems in snapshots: move it to a separate volume that’s in Time Machine’s list of excluded items, and make arrangements for that volume to be backed up separately when the files aren’t in use.

Is the item in a Spotlight index?

Several of those who report repeated warnings or errors in APFS trace them to part of the Spotlight indexes on that volume, which are stored at the top level of all indexed volumes, in the hidden folder .Spotlight-V100. If that’s the case, your next move is to force those indexes to be rebuilt, in the hope that fixes the problem.

To do that, open Spotlight settings, and click the Search Privacy button at the foot of its window. Use the + tool to add the volume on which the problems have been occurring, then close those settings. Leave your Mac for a minute or so, open those settings again, select the volume you just added to the list, and use the – tool to remove it. In the next ten minutes or so, check Activity Monitor’s CPU window, where you should see high levels of activity from indexing processes such as mds and mds_stores, that confirm those indexes are being rebuilt.

Is the item in another special folder?

There are other hidden folders with special roles that appear on volumes and could be the source of APFS errors. These include .DocumentRevisions-V100, containing the document version database. If the problem file is inside that, there isn’t much you can do about it. It may be possible to delete the whole folder, but that will destroy all saved versions of documents on that volume.

It’s just a regular file

If the volfs path resolves to a regular file, then maybe deleting that file will stop the problem from recurring. Don’t expect a backup copy of that file to be any different, though, as any problem with that file could easily recur. 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.

Is your Mac running anything that might break files?

As a final thought, you should consider whether any third-party software might be the root cause of the problem. Normally, such 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.

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.

In last week’s Explainer on snapshots, I stated that “you can safely remove all Time Machine snapshots from that volume except the most recent, which is also the smallest.” This article explains the reasoning behind that.

Why delete snapshots?

Time Machine and other backup utilities make local snapshots on the volumes they back up in addition to copying all changes to backup storage, normally on a different device like an external disk. Because of that, local snapshots are a bonus not a backup. When a volume being backed up is running short of free space, one good method of freeing up space is therefore to delete some of those local snapshots.

Sometimes deleting just one snapshot can free up a lot of space, but estimating the amount likely to be returned is complicated, and to a degree not always readily predictable. If you know one of those snapshots has retained a very large file like a VM or macOS update, you may be able to get away with just deleting the single snapshot, but it’s more usual to need to delete as many as possible, typically just keeping one.

If you are going to retain one snapshot, then by far the smallest is likely to be the most recent, as that almost invariably contains the fewest changes from the current contents of the volume. The oldest snapshot is almost certain to contain much greater changes, so deleting it normally returns the greatest free space. So in terms of meeting your goal of freeing up space, the best strategy is to delete all snapshots except the most recent.

Why keep snapshots?

Although a bonus, a local snapshot is valuable if something goes wrong with a volume and its backup isn’t readily available, either because it’s in a different location or there’s a problem with backup storage. In those circumstances you’re most likely to want that snapshot to be the most recent made, rather than the oldest. So in terms of justifying the retention of any snapshot, the best strategy is to retain the most recent.

What does Time Machine use snapshots for?

Before APFS, Time Machine made the closest it could come to snapshots in HFS+ only when it was unable to perform a scheduled backup. That typically happened on Macs remote from their backup storage, and was intended as the best possible substitute for a proper backup. When Apple introduced APFS in macOS High Sierra, it explicitly stated how its snapshot feature would spare Time Machine from having to run its own code to imitate that.

In High Sierra and Mojave, Time Machine relied on snapshots to determine what needed to be backed up from an APFS volume. It made a snapshot at the start of each backup, and compared that with the snapshot made with the previous backup, a process known as snapshot diffing, and used those differences to determine what should be backed up. That relies on keeping the snapshot made at the time of the last backup; if that’s unavailable, Time Machine has to use another method, and in many cases ends up backing up a lot more than is necessary.

One major disadvantage of snapshot diffing is that it requires the snapshot made for the last backup to be retained until the next backup can be made. When backups are made regularly every hour, that was acceptable, but a Mac that couldn’t back up for several days could end up with an old snapshot occupying tens of GB. Since macOS Catalina Time Machine has therefore been relying on an older method, introduced with HFS+, using the FSEvents database maintained on each volume. That doesn’t require snapshots at all.

Currently, Time Machine will therefore use FSEvents to determine what needs to be backed up from each volume, but there are occasions when that isn’t possible, for example when that database becomes damaged. If that happens, and the snapshot made at the time of the last backup is available, then Time Machine may decide to use snapshot diffing. If that’s not possible, it may fall back to performing a much larger backup than is necessary.

To enable snapshot diffing to take place if needed, Macs that make regular hourly backups should retain their most recent local snapshot.

That becomes complicated and unpredictable in the case of Macs that may skip regular backups, so some snapshots match backups but others don’t. This is confounded by the rule applied for automatic deletion of local snapshots when they are more than 24 hours old, unless that snapshot is the last on that volume. Without matching each snapshot to its backup (or lack of backup), you can’t know which might need to be retained in case Time Machine needs to use snapshot diffing to determine what should be backed up in the future. Whatever you decide to do, if you delete any local snapshots there’s a risk that might result in the next backup being larger than necessary. But the chances are that Time Machine will still be able to use FSEvents rather than snapshot diffing.

Other backup utilities

Time Machine appears to be the only backup utility that can use snapshot diffing to determine what should be backed up. You should therefore be able to delete local snapshots made by other backup utilities without any penalty. If in any doubt, consult their documentation.

Conclusion

If you need to delete local snapshots to free up space in a volume, you can safely delete all except the most recent snapshot, when each snapshot is accompanied by a backup. Where some backups may have been skipped, that is still likely to prove the best overall strategy.

Snapshots are a simple concept that only becomes complex when you dig into the detail. One of the fundamental features introduced in APFS, they are now used extensively, to form the System volume for all versions of macOS since Big Sur, and in many backup systems including Time Machine.

As the name implies, a snapshot is a preserved copy of a volume at a moment in time. Creating one is both simple and lightning quick: APFS makes a copy of the file system metadata for that volume, and retains with it all the data of its files. From then on, the working copy of the file system metadata changes as files are modified, created and deleted. But all the original file data at the time the snapshot was made is retained. That enables you to roll back the live volume to the exact state it was in when the snapshot was made. The snapshot itself (its file system metadata) is kept in the same container as the live volume, and their file data overlaps.

Snapshots rely on another fundamental feature of APFS, a scheme called copy on write. When a file is changed, the data for that file isn’t changed in place in the same storage blocks, but written out to new blocks. This enables the snapshot to retain all the original data for its files, while the live volume consists of a mixture of old unchanged data, and replacements for those blocks that have changed since the snapshot was made.

Size

This leads to the biggest disadvantage of snapshots: when first made, the only additional storage space they require is for their copy of the file system metadata, which is relatively small. Over time, though, as more data blocks are changed in the live volume, the size of the data the snapshot must retain grows, and can after a few weeks become enormous, depending on how active the file system is in that volume. What was initially measured in MB quickly becomes GB, and if you forget about that snapshot, it will become hundreds of GB in size.

Management

While some operating systems allow users to create their own snapshots and maintain them, macOS doesn’t: apps that have the restricted entitlement to create snapshots are required by Apple to maintain them as well. That’s why apps that make snapshots are backup utilities, and are required to have a mechanism for automatically deleting their old snapshots to prevent them overwhelming storage.

Creating a snapshot is almost instantaneous, but deleting one is more complex and time-consuming. This is because the file system has to identify all the old retained data blocks that are no longer required, and allow them to be freed up for re-use. When that’s performed across the millions of files that could be in the snapshot’s file system metadata, it will inevitably take time. It’s also not entirely predictable, particularly when there may be multiple snapshots for that volume.

APFS snapshots are always of whole volumes, although some file systems can make snapshots of directory trees within a volume. Unlike Time Machine’s backup exclusions, each snapshot it makes of a volume it’s backing up contains every file in that volume. If you have large database or VM files, although Time Machine and other backup utilities can exclude them from taking up space in their backups, they can’t exclude them from their snapshots. If you do want to keep such large files, it’s usually better to put them in a volume that doesn’t get snapshots made of it.

Snapshots are also read-only, and once one is made, it can’t be changed. This is beneficial, as it ensures nothing can change the old files and their data. However, it also means that if something goes wrong in a snapshot and it starts throwing errors, you effectively can’t repair it. At present, you also can’t copy a snapshot, which makes it impossible to make a copy of your Time Machine backup storage, as that’s composed of snapshots.

Purposes

Your Mac uses snapshots in three ways:

• local snapshots, typically made by Time Machine and its equivalents on the volumes they back up. Time Machine only keeps those for 24 hours before automatically deleting them for you, although third-party utilities are usually more flexible. You can normally access these, or roll back to them, by mounting the snapshot as a volume.
• backup snapshots, only created by Time Machine and used to store each backup on your Mac’s backup storage. These are created during the backup process by assembling a copy of the local snapshot together with its changed data into a synthetic snapshot, which is how Time Machine makes its backups now.
• the Signed System Volume, created during installation and updating of macOS on the System volume of your boot volume group. This is a snapshot of that System volume, and is mounted and used as the macOS system. Unlike all other snapshots, this has a tree of cryptographic hashes added to it, to verify and seal the SSV. If a single bit is changed in that snapshot, then that change propagates to the top of the tree, macOS will detect it, and invalidate that SSV.

Utilities

In addition to features provided by third-party backup utilities, you can manage snapshots using Disk Utility. Open its View menu and first enable Show All Devices, then Show APFS Snapshots. Select the Data or Macintosh HD – Data volume in the left of the window, and you’ll see a list of all APFS snapshots for that volume, together with an indication of the size of each.

To delete a snapshot in Disk Utility’s list, select it and use the Delete… command from the contextual menu (Control-click). Be careful, though, as there’s no undo. You can safely remove all Time Machine snapshots from that volume except the most recent, which is also the smallest. That latest snapshot is needed when that volume is next backed up by Time Machine. If you remove that too, then the next backup could be a full backup of everything on that Data volume, something best avoided if possible.