The versioning system in macOS is one of its unsung heroes, as it really does just work almost all the time. It remains weakest when working with versions of files in iCloud Drive, though, where slow syncing can silently lose versions. If you do have problems, here’s what I suggest you test, and what you can do to try to fix it.

Check the version database is present

The first step in checking that versioning is able to work correctly is to check that each volume containing files which should have stored versions has the top-level hidden folder named .Document-Revisions-V100 To do that in the Finder, select Macintosh HD (or whatever your boot volume group is named) in the sidebar, press Command-Shift-. to show hidden files, then select each volume in turn.

Near the top of each volume should be a folder with the No Entry sign superimposed, with that name. You shouldn’t normally find them on Time Machine backups, nor on Macintosh HD itself, as that’s actually the System volume. Volumes which are currently empty may also not have the folder unless they’ve previously stored user files with versions. Check your current Data volume in the path System / Volumes / Macintosh HD instead.

If you want to check that the service is running correctly, look for revisiond in Activity Monitor. This is started by /System/Library/LaunchDaemons/com.apple.revisiond.plist, and runs as root.

Create test versions

Open an app like TextEdit or my own Rich Text editor DelightEd, create a new document, save it, and generate some test versions. Type the line
First
then save (Command-S), and repeat with Second and so on, saving each time. Note that if you save to iCloud Drive, you should allow time after each save for the version to sync with iCloud, or the versions saved may get skipped.

Close that document, open it again, and inspect its saved versions using the Browse All Versions… command in the Revert To sub-menu of the File menu. Step back to the first version of the file, and you should then see each new version add a line in progression.

Close your test document, open Revisionist, and open the document using that. This should show each of the previous versions, together with the current one. Double-click on any version to see its preview and open that version using the default app for that type of document, in this case Rich Text, which is normally edited using TextEdit.

For each selected version, Revisionist shows the path to that version in the locked and hidden .DocumentRevisions-V100 folder on the same volume on which the current document is stored.

Review other documents with versions

Look for other documents with saved versions, and particularly those that have many versions, which could be causing a problem with the database. For this, use Revisionist’s Crawler, opened using that command in its Window menu. Click on the Scan button and select a folder. Revisionist will then perform an exhaustive search and report all the files with saved versions in that folder, together with the number of versions for each document. Avoid scanning whole volumes, as they could require a long time and a lot of memory.

Check the app supports versioning

Most apps developed using the standard AppKit library for macOS should support versioning. To confirm that they do, open the app and look for the distinctive Revert To sub-menu in the File menu. If that app doesn’t show that, it’s very unlikely to support versions, and there’s nothing that you can do about it apart from complaining to its developers.

What can you do?

Because this is a closed database with a folder which is locked away from inspection, your remedies are as limited as its problems should be rare.

As a first step, try removing excessive versions which may have accumulated on old files and are no longer required. The simple way to strip them all is to duplicate the file and put the original in the Trash. If you want to retain some of those versions, you’ll need to edit them using Revisionist.

If the whole versioning system is misbehaving and you’re running an unsealed version of macOS, Catalina or earlier, you can try re-installing macOS. There’s little point in doing that with Big Sur or later, though, unless you have broken the seal on the System. Re-installing macOS while retaining the same Data volume won’t affect the database either.

If you decide it’s best to start from scratch, archive any version sets you want to retain using Revisionist or Deep Tools, then clone your Data volume to another disk, format the original volume, and clone the volume back again. As the version database isn’t copied when cloning, nor when restoring a Time Machine backup (in recent versions of macOS, at least), this will create a new, empty version database, which should clean out any detritus and start that volume off afresh. If you prefer, you could just delete the .Document-Revisions-V100 folder, authenticating when prompted, although that can leave error messages if you try to access old versions of documents in apps.

If you archived any version sets, this is the time to add them back using Revisionist or Deep Tools. That should confirm that your versioning system is working again.