When Apple announced APFS at WWDC ten years ago, snapshots were demonstrated as one of its major features, and intended to form the basis of Time Machine’s backups in the future. Shortly after its initial release in High Sierra, Rich Trouton at Der Flounder documented their use, including how to roll back to a snapshot using Time Machine System Restore in Recovery mode. Apple described this in a support note now replaced by its successor, last revised six months ago, which carefully avoids any mention of rollback.

Snapshots are widely available in modern file systems, in some being referred to as shadow copies, and rolling back to them is a popular if not indispensable feature. Except in APFS, where there appears to be only one supported method, which is severely restricted, as I described last week. That enables you to roll back your Mac’s current Data volume to a snapshot, but doesn’t work for any other volume as far as I can discover.

Disk Utility can display and delete snapshots on any mounted disk, but can’t create or roll back to them. Its command line equivalent diskutil has the same limits (unless you’re ChatGPT). tmutil appears to be the only way to create a snapshot in macOS, but can’t perform that for an arbitrary volume, only the current Data volume and those being backed up by Time Machine.

If I wanted to make a one-off snapshot of a volume on an external SSD, I’d thus have to turn to a third-party utility. Even here I’m up against Apple again, as the API for snapshots is controlled by two restricted entitlements, com.apple.developer.vfs.snapshot for creating and deleting them, and com.apple.private.apfs.revert-to-snapshot for rollback. So far, Apple appears to have approved only apps that make backups and automatically delete their old snapshots to prevent them from overwhelming storage space, and I’m not aware of one with the com.apple.private.apfs.revert-to-snapshot entitlement to allow rollback.

As Adam Leventhal has documented in his open source command tool snaputil, the API call fs_snapshot_revert() is used to perform a rollback, but without the com.apple.private.apfs.revert-to-snapshot entitlement is non-functional.

Having drawn a blank with Apple’s tools, you might feel tempted to ask AI to help. If you’re lucky it might talk you through using Time Machine System Restore in Recovery mode, although as we’ve seen that can’t help with any volume other than the current Data volume.

ChatGPT’s responses to two queries from different people are more concerning, as it repeatedly asserted that you can roll back using a completely imaginary verb with the diskutil command, in one case using a command of the form
diskutil apfs revertToSnapshot -n com.apple.TimeMachine.YYYY-MM-DD-HHMMSS /
or using
diskutil apfs revertToSnapshot disk1s5 -n com.apple.TimeMachine.YYYY-MM-DD-HHMMSS
instead.

I have checked that in normal user mode and in Recovery mode, only to be told the revertToSnapshot verb isn’t recognised. With the aid of virtual machines, I’ve confirmed that as far back as macOS 12 Monterey, and there’s absolutely no sign of it. When challenged, ChatGPT maintained that it was “directionally right” that revert capability exists in APFS, as we already know from Time Machine System Restore, and that Apple’s entitlement structure “proves it”. It’s a shame I had to do so much checking to confirm that ChatGPT was plain wrong, and had apparently made up those commands.

Not being able to make a one-off snapshot of a volume on an external SSD might appear a small if annoying oversight, but it has consequences. Snapshots are not only blazingly quick in rollback, but they are also the only means of restoring some important volume content, such as document versions, which is easily demonstrated.

When files are restored by copying from a mounted snapshot, all their saved versions are lost. They are also lost from Time Machine backups, and in any case would be lost during migration. The only way to preserve those versions would be using a third-party tool such as my Versatility or Revisionist.

Ten years after Apple first promised us snapshots in APFS, we still don’t have access to their full capabilities, and their use remains largely undocumented. Yet they’re readily available in competing operating systems and file systems.

There are often times when a laptop Mac has to be separated from its backup storage. This article explains how you can use local snapshots to cover those, and roll back to a snapshot in the event of a problem.

Snapshots are one of the most valuable features new to APFS. In the days of HFS+, Time Machine offered something similar that required around 10,000 lines of code, and still wasn’t as good as a real snapshot. Although they’re no substitute for a proper backup on a separate disk, snapshots can get you out of a hole when nothing else will.

A snapshot is simply a copy of the file system for a single volume at a moment in time. The file system data itself is relatively small, but to ensure your Mac can roll back to that, it has to retain changed and deleted storage from that moment on, and that makes increasing demands on space. So you only want to keep snapshots for the shortest time necessary, or they can quickly consume tens and even hundreds of GB.

If you want to restore just part of a snapshot, you can mount it as a volume in the Finder and copy the folders and files you need from there, as if it was a backup. This article considers how you can address a bigger problem, where your best choice is to return the whole of your Mac’s Data volume to how it was when a snapshot was made.

Make a snapshot

The essential ingredient is, of course, a snapshot. If your laptop Mac is already making Time Machine backups, when its backup storage isn’t available it should continue making snapshots instead of full backups, so you’re covered.

You don’t need to be using Time Machine to make a snapshot of your current Data volume, though. Any Mac will make one when you enter the command in Terminal
tmutil snapshot

Although third-party backup utilities can also make snapshots, you may well find they don’t work with Apple’s rollback feature, and should check with their documentation before relying on them.

Roll back

To roll back your current Data volume to a previous snapshot, first check in Disk Utility that the snapshot you intend to use is still available, if necessary using the command Show APFS Snapshots in its View menu when the Data volume is selected. That will list all those available.

Then shut your Mac down and start it up in Recovery mode, passing through to the main window in Recovery Assistant.

Select the top item to Restore from Time Machine, and click Continue.

Click Continue to move past its opening window.

Select the boot volume group here, normally named Macintosh HD, then Continue.

You’ll then be offered the list of available snapshots. If you don’t see any here, then I’m afraid you’re out of luck, and won’t be able to roll back using Time Machine System Restore. Click Continue.

Check in this warning dialog that you’re going to roll back to the correct snapshot, then click Continue.

The rollback takes but the twinkling of an eye, following which your Mac will automatically restart back into normal user mode, with the snapshot contents as its Data volume. If you made the snapshot yourself in Terminal, Terminal will still be open, displaying that command, just as it was when you made that snapshot.

The only side-effect to be aware of is that all snapshots made after the one you rolled back to have now vanished, and can’t be retrieved. That’s because you have effectively forked the file system from the moment of the snapshot you have rolled back to, and more recent snapshots can’t fit in with the changes made by the rollback.

Finally, I have heard of commands that are claimed to perform rollbacks, including one for diskutil apfs. I believe those to be bogus. As far as I’m aware, Terminal in Recovery doesn’t offer a command tool to perform snapshot rollbacks, but I’ll be happy to be proved wrong.

Key points

• Use a Time Machine snapshot, or tmutil snapshot in Terminal.
• Roll back in Recovery, using Time Machine System Restore.
• Rolling back is almost instant, but deletes all later snapshots automatically.

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.