Fixing problems with iCloud and iCloud Drive is completely different from any other troubleshooting in macOS, because:

• Almost all problems are delays in or failure of synchronisation.
• Documentation is almost entirely lacking.
• There are almost no tools to help diagnose or fix problems.
• Even those experienced in reading the log find it hard to use for diagnosis of iCloud problems.
• There’s a very limited range of potential solutions.

Here I’ll consider those factors that you could change, and how they might help alleviate synchronisation problems in both CloudKit databases and iCloud Drive files.

Configuration

If you have more than one Mac or device that connects to the same iCloud account, then consider enabling the Content Caching server on your Mac. While your Macs and devices are connected to the same local network, it’s likely to improve sync performance significantly. Pick the Mac that’s running longest through the day, ideally one that isn’t shut down at night, and has sufficient free storage, which is often on an external drive. Enable this in System Settings > General > Sharing > Content Caching, and in its Info dialog set it to share All Content.

When each networked Mac or device next starts up, it should then connect to that server to obtain cached content. This not only reduces the amount that has to be obtained from outside the local network, but should also make syncing significantly quicker.

Settings

There are two other controls whose settings you should reconsider. Optimise Mac storage, in System Settings > [Apple ID] > iCloud, gives macOS the power to evict files from local storage whenever it feels appropriate. Although this can save valuable local storage space, it can also lead you into the unfortunate situation that your Mac has insufficient free space for all those evicted files to be downloaded. Should you then need to download many of them, you would run out of space.

That’s a particular risk if you also put Desktop & Documents Folders into iCloud, in System Settings > [Apple ID] > iCloud > iCloud Drive, the other control you should reconsider. This is most useful for Macs with limited local storage, which are also those at greatest risk of ending up with insufficient free space to download all evicted files.

Generally, syncing problems are less likely if both those options are disabled.

Networking

Before trying to fix any iCloud syncing problem, ensure that your internet connections are working well, and that iCloud service status doesn’t report any known problems. If you don’t, you could waste hours trying to solve a problem that can’t be fixed at your end, or which could have been solved with a quick visit to Network settings.

Actions

When individual files aren’t syncing properly, there are three actions you could apply to them:

• remove the file from iCloud Drive and put it back into a local folder;
• download the file to local storage;
• evict the file to iCloud storage.

The latter two are available in my free utilities Cirrus and Bailiff, and in the Finder’s contextual menu as Download Now and Remove Download respectively.

If Desktop & Documents Folders aren’t enabled in iCloud, moving files that appear to have stuck syncing can let the rest of the sync complete successfully. Once that’s done, you can try moving those files, one at a time, back into iCloud Drive, giving each time to sync completely before moving the next. When it works, this can be the simplest and most effective way to restore normal iCloud Drive function.

Download and eviction are only available when the current status of a file allows. Files have two stable states: downloaded and evicted, and in each case the opposite is the command available. Thus, an evicted file can’t be evicted again and will only offer Download Now. The Finder also calls for the download of most evicted files you care to select in order to access their metadata and for QuickLook to display a custom icon.

Connections

Because of those limited possibilities, many users try disconnecting that Mac or device from iCloud, then reconnecting it again. There are four ways of doing that:

• Shut the Mac or device down, wait a few seconds, then start it up again. Shortly after the user logs in, macOS will attempt to sync with iCloud. As this is all ‘natural’ not forced, this should be your first choice if previous file actions have been unsuccessful.
• Shut down all Macs and devices connected to that iCloud account, and start them up one after the other, allowing each to sync fully before starting the next one up. This is most appropriate when there’s a CloudKit-based service that’s failing to sync across devices.
• Turn iCloud off altogether on the Mac or device that isn’t syncing properly. Although commonly advocated as the first choice, it turns out to have undesirable side effects, for example if Desktop & Documents Folders are enabled, and when Apple Pay is activated, and can lead to data loss if you’re unlucky. It’s thus best held in reserve as a last-ditch measure if nothing else works.
• Recover as much iCloud data as possible to local storage, disable all iCloud connections, then start from scratch. Even if you use iCloud relatively little, going back to square one will require considerable time and effort, and should only be considered if nothing else has worked.

Tools

Tools available include:

• The Finder’s contextual menu (Control-click, etc.) offers Download Now and Remove Download (evict).
• brctl is the only command tool of any value. Its man page shows how to use it to download and evict files from the command line. Other verbs are really only useful to Apple’s engineers, as they aren’t explained. brctl dump might appear useful and interesting, but it usually writes several MB of opaque information that isn’t of any obvious use.
• My free Cirrus, offering download/evict, an upload test, a custom iCloud Drive browser, and custom log access. There’s also my free menu bar app Bailiff that gives ready access to download and evict, although that’s now available in the Finder.

If you know of other tools of value in diagnosing and fixing iCloud problems, please let me know.

Summary

• Enable Content Caching server if possible.
• Avoid Optimise Mac storage if possible.
• Avoid putting Desktop & Documents Folders into iCloud if possible.
• Check internet connections are working well, and iCloud service status.
• Try moving stuck files back to local storage. If that lets syncing complete, move those files back into iCloud one at a time.
• Shut the affected Mac or device down, then start it up again.
• Shut all Macs and devices down, then start each up one at a time and allow them to sync fully before moving on to the next. This can be best for CloudKit database syncing.
• Only turn iCloud off altogether as a last-ditch measure. Be prepared for side effects such as on your Wallet, if using Apple Pay.