Following the iPhone’s launch in 2007, as it was taking the world by storm, cloud services started to become popular. Apple released MobileMe in 2008 and followed it with iCloud in 2011; Microsoft OneDrive was initially released as SkyDrive in 2007, and Dropbox was launched in 2008. Since then cloud services have become increasingly important to mobile devices with their limited storage capacity, and have proved a good source of revenue for Apple and others.

For the first decade, each cloud service did its own thing, and integrated more or less with macOS. That started to change in 2019, and since 2021 Apple has encouraged the adoption of its new File Provider framework in macOS and its other OSes. iCloud Drive adopted it fully in macOS Sonoma in 2023, and most major cloud services have migrated to it now. This framework concerns itself with cloud-based file storage, branded by Apple as iCloud Drive, rather than shared databases such as Calendar and Contacts.

The File Provider framework brings consistency to the ways that users and their apps access files that are stored remotely in the cloud. All that is expected of the cloud service provider is to implement one or two extensions to interface between macOS and their servers. Apple describes these for developers in its documentation.

There are two models provided for this, depending on whether local copies are maintained of all files stored in the cloud:

• Replicated file providers are responsible for keeping local copies of all files that are also stored in the cloud, by syncing their contents. This requires them to upload any changes made locally, and to download all those changes made to the remote copy. In iCloud Drive, this applies when Optimise Mac Storage is turned off.
• Nonreplicated file providers have similar responsibilities, but full local copies of files aren’t required, allowing the user to remove some or all files from local storage. Those that are removed are then retained in local placeholders, whose management is also the file provider’s responsibility. In iCloud Drive, this is used when Optimise Mac Storage is turned on, and files can be evicted from local storage to leave just the placeholders.

Before iCloud Drive migrated to being a file provider, it used local stub files as placeholders when operating in nonreplicated mode. Those have since been replaced with dataless files and folders consisting only of file attributes and extended attributes, with no file extents containing the file’s data. The file provider is then responsible for downloading and restoring the data for those placeholders when required.

When a dataless placeholder file is to be used locally again, its data has to be downloaded from the cloud service, and the local dataless file is materialised by adding that back. Because that local file never lost its metadata, those remain intact, as should any locally stored versions. Although the APFS Reference details flags for dataless snapshots, it doesn’t contain any information about dataless files, which do have a flag to mark that state in their attributes, as explained here.

A file provider can offer additional features, including the ability to mark certain files and folders so they aren’t evicted from local storage, a feature commonly known as pinning, and originally offered by iCloud’s competitors.

iCloud Drive adopted the File Provider framework in 2023, and after initial trauma among some users who had come to rely on bugs in its previous implementation, it has brought general improvement. Third parties were reluctant at first, but once they had produced File Provider extensions and their bugs were ironed out, it has ensured better integration with apps and other services, as intended.

iCloud has changed a great deal in the nearly 15 years since its introduction, and now provides many discrete services. These include synchronisation of app databases using CloudKit, file storage and sharing using iCloud Drive, update and support services for macOS and Apple’s other OSes, and a loose group of miscellaneous services including Private Relay.

Well-known examples of those include:

• CloudKit – shared calendars, address books and notes;
• iCloud Drive – folders and files in the Finder’s iCloud Drive location;
• macOS support – XProtect updates for Sequoia and Tahoe, optional language support and additional dictionaries downloaded on demand;
• miscellaneous – iCloud+ Private Relay, Find My.

One of the most common confusions is to assume that a problem with one service cause problems with others. Although they can, that all depends on where the fault lies.

There are also two major online services provided by Apple that are separate from iCloud: its software update servers to deliver OS updates as well as security data and other system support through Software Update; Private Cloud Compute to deliver off-device AI services.

Network basics

All iCloud services have their own local client, such as CloudKit for syncing shared data, which in turn relies on low-level network services in macOS. Those communicate through your network’s router, and so pass out to the Internet to connect with a remote server. Although Apple does have at least one of its own data centres, much of iCloud is thought to be hosted on Amazon Web Services (AWS) and/or Google Cloud Platform.

These are important details when investigating iCloud problems. There’s no point in fiddling with local iCloud settings if the problem results from any link in this chain beyond your Mac. One of the most valuable early steps is to point your browser at Apple’s local service status page and check whether that service is reported as working normally. If that loads briskly, works as expected, and claims the iCloud service you’re having problems with should be working normally, you can turn your attention to what might be going wrong in your Mac.

One important factor to be taken into account is whether a local Content Caching server is in use. Unless iCloud content is excluded, a local server should cache changes in iCloud data, enabling other Macs and devices to sync within the local network. Enabling a Content Caching server can itself address some iCloud problems, and is well worth considering.

Testing

The most common fault with iCloud’s services is failure to sync local contents with those stored in iCloud. Failures are hard to investigate even in a controlled test, as there’s no way for a user to tell directly what’s going on in iCloud without relying on another Mac or device syncing (or the iCloud.com web service updating). The following tests are relatively quick and simple, and can provide helpful information about the state of iCloud services on your Mac.

CloudKit

The only controls provided for CloudKit are those in the iCloud section of your Apple Account settings, and any in apps that use CloudKit. For each service you use, ensure that Sync this Mac is enabled before going any further.

To test syncing of Notes, open the app on your test Mac and other Macs and devices. Write one note in the test app and wait for it to sync to the others. On one of the other systems, write another note, and wait for that to sync to the test Mac. Syncing isn’t immediate even if you’re using a local Caching server, but it should occur within a couple of minutes when there are good connections to iCloud.

There are times when syncing can take much longer. To ensure that CloudKit server resources are shared fairly, CloudKit imposes limits on transfers, and can throttle traffic. Throttling is likely to occur when a CloudKit app issues many requests over a short period, or uses CloudKit inappropriately, perhaps triggering simultaneous peaks in request rates from several devices at the same time. In some situations, where you suspect that one or more CloudKit-based apps are causing throttling or hitting limits, you can disable their syncing to see if that enables other apps to sync better.

The definitive way to investigate CloudKit problems is in the log, and is a fearsome task even for developers, as detailed here.

iCloud Drive

The most important control over iCloud Drive is in the Drive item of the iCloud section of Apple Account settings, where Sync this Mac must be enabled. You should also check syncing in the list of apps there.

The Optimise Mac Storage control determines how iCloud Drive works. In the past, it relied on its own features in macOS, and for many those were flawed. Evicting a file from local storage left a local stub file as a place-marker, but in 2021-23 iCloud migrated to use a new FileProvider framework common to all cloud services.

Since then, iCloud Drive has worked in either of two distinct modes:

• When Optimise Mac Storage is turned off, iCloud Drive is a replicating FileProvider, and maintains complete local copies of all files stored in iCloud servers. This prevents you or macOS from removing their downloaded data.
• When Optimise Mac Storage is turned on, iCloud Drive is a non-replicating FileProvider, and can remove the downloaded data of local files, a process known as eviction. Rather than leaving stub files, the same files remain but they are dataless. You and macOS can thus choose whether to evict files or download them, and you can opt to keep them downloaded, or ‘pinned’ locally.

iCloud Drive syncing is also believed to be subject to throttling to prevent servers from being overwhelmed, although that appears infrequent and lasts but a few hundred milliseconds if it does occur. Files for transfer are divided into chunks of just over 15 KB, although the system maximum may be as large as 28 MB or even 33 MB. Some iCloud servers may also impose a maximum limit on the number of connections.

The simplest way to test iCloud Drive syncing reproducibly is using the Test Upload feature available in the Window menu of Cirrus. This transfers a 1 MB file named co.eclecticlight.Cirrus.data, which should appear almost instantly at the top level of the iCloud Drive folder, so is readily visible on Macs and devices connected to the same iCloud Drive account. There’s also a Clean up Test command to delete that test file.

Having established that your iCloud Drive does sync promptly using that test file, the more difficult problem is to discover why some files appear to be stuck. Unfortunately, the best way to identify them is from the log.

macOS support updates

Testing updates is harder, unless your Mac is running Sequoia or later and isn’t yet running the current version of XProtect. You can check that by comparing the version installed given by
xprotect version
with that available from iCloud, revealed by the command
sudo xprotect check
If the second version is greater than the first, then running
sudo xprotect update
should download and install the update, a worthwhile procedure in any case.

Tests work, but iCloud still doesn’t

iCloud is one area where you shouldn’t simply follow the adage of “try turning it off and back on”. Repeatedly changing its settings without good cause can make problems worse rather than solving them. The best reset or off switch for iCloud is to shut a Mac or device down, to allow iCloud services to shut down as normally as possible, then for them to be re-established when starting up again.

This applies most particularly to the Optimise Mac Storage setting. As that changes the type of FileProvider used, it can take many hours or days to sync correctly to a new setting. Although not specifically recommended, starting up in Safe mode, leaving the Mac to settle for several minutes or longer, then restarting back into normal user mode, can sometimes help.

During the transition from the old iCloud Drive to the new FileProvider mechanism, some users found it necessary to leave their Macs syncing with iCloud Drive for several days. That can still be a worthwhile strategy for what appear to be otherwise intractable problems with syncing.

Persistent problems should be taken to Apple Support, as only they have access to specialist iCloud engineers.