For an unfortunate few of us, upgrading to macOS Sonoma brought a host of problems with iCloud Drive, in some cases leaving Macs apparently trying to download the entire contents of their iCloud storage before they could work normally again. While trying to understand what could have caused this, I was surprised to discover that upgrading to Sonoma has brought radical change to iCloud Drive, specifically in the way that it handles evicted files in local storage.

Eviction and stub files

In the recent past, when a file has been evicted to iCloud (its download being removed from local storage), it has been represented by a placeholder or stub file in its original folder on the Mac. Taking the file named MyDocument.extn as an example, in the more distant past it might have been represented by a stub file named .MyDocument.extn-tef.icloud, but more recently that would have been named .MyDocument.extn.icloud, and was typically less than 200 bytes in size.

Stub files retained all their original extended attributes, including any Resource fork, and when their data was downloaded from iCloud they were reconstituted into their original files, original names, extended attributes and all. That explains why files can retain custom icons, stored in their Resource fork, when accessed from the Mac that uploaded them to iCloud Drive, but the same file loses its custom icon when accessed from another Mac, as iCloud Drive won’t accept Resource forks or extended attributes larger than a total (across all extended attributes) of around 32,650 bytes.

File structures

Before Sonoma, with Optimize Mac Storage turned on and almost all my Numbers spreadsheets stored in iCloud Drive evicted from my Mac, most were marked in the Finder by the characteristic iCloud icon with a downward-pointing arrow, as seen below in Ventura in February 2022.

Browse them using my iCloud utility Cirrus, and you can see their many stub files, each with names starting with a stop or period, and less than 200 bytes in size.

Here, 20 months later in Sonoma 14.0, rather fewer of those spreadsheets remain evicted, and they still show the same icon in the Finder.

But when viewed in Cirrus’s browser, they bear the same names without leading stops or periods, and they have the same file size as fully downloaded files. There are no stub files to be seen, and the only indication that these files are evicted and not stored locally is in their Status: evicted files are shown as NotDownloaded, while those stored locally are Current. Status is here obtained from ubiquitousItemDownloadingStatus in URLResourceValues.

Why was Sonoma so disruptive?

While many of us upgraded to Sonoma without any hint of iCloud trouble, some have suffered serious problems. These appear most likely to affect Macs with Optimize Mac Storage turned off, some of whose files have been evicted. What happens then is that, shortly after completing the upgrade to 14.0, iCloud appears to perform a full resync of every file stored in iCloud Drive. Resynchronising local files with those stored remotely in iCloud Drive isn’t normally so disruptive or destructive, though.

There are two important clues that this isn’t just a full resync, but something more major:

• Normally, Time Machine backups work fine during iCloud Drive syncs, and aren’t aborted. For some, backups were repeatedly abandoned until iCloud had completed syncing.
• One report (from Wade, thank you) states that files that have been resynced in this way also undergo stripping of their Resource forks, or com.apple.ResourceFork extended attributes, including custom icons.

These are consistent with macOS completely wiping local iCloud Drive storage and downloading its entire contents afresh, rather than simply resyncing. That may have been a bug, but I suspect it’s more likely to have been a deliberate decision when trying to convert folders and their contents to this new format. This is most likely to occur on systems with Optimize Mac Storage turned off, but with stub files indicating that files had been evicted despite that setting.

Summary

• Sonoma brings radical changes to iCloud Drive, including the removal of traditional stub files for those files evicted to iCloud.
• Those changes may result in macOS completely wiping local iCloud Drive storage and downloading its entire contents from iCloud.
• That appears more likely to occur if you have Optimise Mac Storage turned off, and some files evicted to iCloud Drive.
• If you’re not prepared to turn Optimise Mac Storage on before upgrading to Sonoma, you may have to wait for all your files stored in iCloud Drive to be downloaded to your Mac.

Postscript

I suspect these new evicted files take advantage of a trick in APFS: as far as I can tell, they consist of the file with its attributes and extended attributes intact and stored locally, but no extents for its data. Thus, when you ask for the file size, it returns the size it would be when downloaded, although the file only takes the space required for its attributes and extended attributes, until it has been downloaded. As Apple promised, these are dataless files.

Apple provides more information about dataless files in this article. Notably, it states that you can tell whether a file is dataless by calling stat or getattrlist and examining if SF_DATALESS is present in stat.st_flags.