iCloud is one of those features in macOS which works almost all the time for the great majority of users, but is vulnerable to problems when Apple makes changes to it, typically in a major new version of macOS. Just a few years ago, changes which had already been announced had to be cancelled early in beta-testing because of the devastation they caused to existing iCloud accounts. Thankfully the changes to iCloud in Monterey are relatively minor, but have still caused plenty of users to complain of syncs that seem never to end, and other issues. This article aims to provide a little understanding, and maybe even help you to a solution.

How iCloud works

iCloud is a vast distributed database, in which each user’s data and files are just a few of its contents. So when you put a file into iCloud Drive, what your Mac does is negotiate that with the database server, which then stores the file as a record containing its data and metadata.

On your Mac, files in iCloud Drive exist in one of two states: a local and complete copy, which is kept in sync with that held in iCloud, or a stub file which relies entirely on downloading the file contents from iCloud when you want to access it. The first of those has been downloaded, and the second has been evicted from local storage. Those can be told apart in the Finder and elsewhere using standard icons: that showing a cloud with a downward arrow means that item has been evicted, and the file shown in the Finder is but a stub.

Normally, unless you enable Optimise Mac Storage in the iCloud section of the Apple ID pane, the contents of your iCloud Drive are kept in a downloaded state, ensuring that you can use them immediately. Enabling optimisation lets macOS manage whether each item is downloaded or evicted. In theory, provided there’s sufficient local free disk space, all recently active items should be kept downloaded. When pressure on free space grows, macOS will progressively evict your files until there are just folders full of stubs.

In practice, this distinction isn’t always as clear. Some items still seem to get evicted even when optimisation isn’t turned on, and with it enabled and ample local free storage, less used files still get evicted. I have two apps, Cirrus and Bailiff, which give you better control over this. If you’re going somewhere with poor Internet, for instance, you can use them to download all the files you need before you go. They don’t, though, guarantee that at the last minute macOS won’t decide otherwise.

Desktop & Documents

There’s one major decision you make about how iCloud Drive works on your Mac, and that’s whether to put your Desktop & Documents Folders in iCloud, controlled in the Options for iCloud Drive in the Apple ID pane again.

When Apple first released that, I nearly lost my entire Documents folder when it was sucked up into the cloud. As a result of the experiences of many users at that time, I recommended that no one should even consider using it until it became more reliable, and potentially less destructive. It has since matured, but can still give rise to serious problems.

The worst come when you have ample iCloud storage and relatively little in your Data volume. It’s then easy to end up with more files in iCloud than your Data volume could ever store. That poses a problem, as you can only continue with many or most of those files evicted, and are unable to download them all. You are then a prisoner of iCloud, with documents that you can’t store locally. For this and other reasons, I still urge users not to enable Desktop & Documents unless their Documents folder is going to remain small, perhaps by adding a local folder to their Home folder for locally stored documents only, which defeats the purpose.

It’s also the case that those Macs with Desktop & Documents enabled are most likely to encounter problems when iCloud changes, for example with a new version of macOS. And because they’re more dependent on iCloud, the impact of those problems is greater too.

Databases

Most other items listed in the iCloud section of Apple ID, from Contacts to Stocks, don’t store their data in simple files, but in databases. When your local apps sync with iCloud, database records are exchanged. You have essentially no control over those, other than whether to enable the service or not. Tracking file syncing with iCloud is complex enough using the log; you don’t stand a chance of doing that with databases.

Check your Internet connection

This has improved greatly in Monterey, with the addition of a new command tool which is simple to use and highly informative: networkQuality. To use this, open Terminal, and type
networkQuality
After a pause for thought, you should see something like
==== SUMMARY ====
Upload capacity: 554.709 Kbps
Download capacity: 3.424 Mbps
Upload flows: 20
Download flows: 20
Responsiveness: Low (44 RPM)
This is explained in fuller detail by Dan Petrov, and is far more useful than just for the investigation of iCloud problems. And don’t worry, I’m waiting for a major upgrade to my Internet connection.

Check the service

iCloud, like Apple’s other services, doesn’t work perfectly all the time. Before going any further, open Apple’s service status page here and check whether it might have a known problem.

Run a Cirrus sync test

Cirrus offers a standard test based not on a database sync but on transferring one 1 MB file to iCloud Drive. Sometimes merely running this test can prove sufficient to kickstart iCloud syncing, but its primary purpose is to verify that iCloud sync is working. If you fancy going deeper, you can also use it to review what happens in the log during that process.

The first time that you attempt this, you’ll find it best performed when everything else on your Mac is quiet, perhaps first thing in the morning before you’ve started any apps, and certainly before opening apps which use iCloud. Running the test is simple: as your system clock reaches 00 seconds, press Command-1 in Cirrus, or release the Test Upload command in the Window menu. Watch what happens with the iCloud sync circle in a Finder window, and note the number of seconds when that icon fills and is removed.

If you want to examine that in the log, use the Open Log Window command in the Window menu, set the Start time to just before you initiated the test upload, and the End time to at least the time that iCloud sync completed, and no less than ten seconds later (in High Sierra and earlier, 20 seconds). Finally click on the Get log button, and you’re ready to study what happened. To clean up the test files, use the Clean Up Test command in the Window menu.

Cirrus performs the test as follows:

1. It first writes a 1 MB file containing 0x88 bytes as data to ~/Library/Preferences/co.eclecticlight.Cirrus.data
2. It then creates a URL to a new file co.eclecticlight.Cirrus.data in your iCloud Drive, at the path ~/Library/Mobile Documents/com~apple~CloudDocs/co.eclecticlight.Cirrus.data
3. If that succeeds, it removes that new file and copies the 1 MB file from ~/Library/Preferences/co.eclecticlight.Cirrus.data into your iCloud Drive at ~/Library/Mobile Documents/com~apple~CloudDocs/co.eclecticlight.Cirrus.data
4. If any step in that fails, Cirrus reports that it was unable to transfer the test file in an alert.

The Clean Up Test command simply deletes the two files ~/Library/Preferences/co.eclecticlight.Cirrus.data and ~/Library/Mobile Documents/com~apple~CloudDocs/co.eclecticlight.Cirrus.data.

Even without going near the log, this is still useful as a test of basic iCloud Drive function. You’ll find a detailed account of the log extracts in this article.

Cirrus’ Help book contains more information about how to use Cirrus, and iCloud Drive more generally.

Turn it off and back on

Having got this far, you’re no doubt waiting for the secret technique which will fix any remaining problems. I’m sorry to disappoint, but, apart from downloading or evicting items, the only control you have as a user is the on-off switch: with individual iCloud services in the iCloud section of Apple ID, and signing out and back in using the Overview section.

Before you use any of those, ensure that you’ve downloaded all important documents, something Cirrus and Bailiff can help with, and where necessary made local copies of those outside your iCloud Drive folder.

Each person who is reduced to trying this arrives at what they consider is the most effective solution. It might even be a matter of putting your Mac to one side and letting it get on with it for a day or two, or signing out, shutting that Mac down overnight, then signing in again. All I can do is wish you every success. And if all else fails, then sometimes Apple Support can help.