0%

Cleaning Up Over a Hundred GB of iCloud Drive Cache on macOS

The previous post dealt with lsd hogging the CPU. While investigating that, I also took a look at the disk: the data volume of this MacBook Pro is 466 GB in total, 389 GB were already used, and only 42 GB were available, i.e. 91% full. Drilling down with du level by level, ~/Library/Caches alone took 106 GB, 102 GB of which were under CloudKit.

Deleting these caches is easy; the hard part is figuring out where they came from. Below I first describe the cleanup, and then come back to three questions: where the cache came from, how to notice it early next time, and how to avoid accumulating so much of it again.

Background

bird

The full path of bird is /System/Library/PrivateFrameworks/iCloudDriveCore.framework/Versions/A/Support/bird. As the framework it lives in suggests, it is the iCloud Drive daemon. iCloud Drive files are stored under ~/Library/Mobile Documents/: the files in iCloud Drive itself are in com~apple~CloudDocs, and the other subdirectories, named after apps, are each app's own iCloud container. bird's cache is kept somewhere else, namely ~/Library/Caches/CloudKit/com.apple.bird/.

Cloud-only files

With "Optimize Mac Storage" turned on, macOS moves files that have already been uploaded off the local disk when space runs low, leaving only a placeholder. The output of defaults read com.apple.bird contains the line "optimize-storage" = 1, which, judging by the name, means the option is on for this machine.

For files that live only in the cloud and haven't been downloaded, ls still reports the full size, but they don't actually take up disk space. Take a directory in iCloud Drive where I keep system images as an example:

1
2
3
cd ~/Library/Mobile\ Documents/com~apple~CloudDocs/<some directory>
ls -lah
du -sh .

ls lists two macOS restore images (.ipsw), one 16 GB and one 14 GB, yet du reports 0B for the whole directory. These files don't have an .icloud suffix in their names, either. So to see how much space iCloud Drive actually uses locally, use du, not the sizes reported by ls.

Clones on APFS

When copying a file on APFS, a clone can be made instead of a real copy, which is what cp -c does. A clone shares the same data blocks as the original, so the copy is nearly instant and takes no extra space; only when one of them is modified is new space allocated for the modified part. Conversely, if you delete one of them, those data blocks are not freed as long as the other one still exists.

Investigation and Cleanup

Where the cache is and what's in it

First, the sizes of the subdirectories under CloudKit:

1
2
3
4
101G	~/Library/Caches/CloudKit/com.apple.bird
60M ~/Library/Caches/CloudKit/com.apple.syncdefaultsd
36M ~/Library/Caches/CloudKit/com.apple.CloudDocs.iCloudDriveFileProvider
7.1M ~/Library/Caches/CloudKit/cloudd_db

The other services' caches are all within a few dozen MB; only bird's is absurdly large. Digging further, nearly all of the 101 GB was in com.apple.bird/<hash>/MMCS/ClonedFiles/, where <hash> is a 40-character hexadecimal directory name, written this way below. ClonedFiles contained 3643 files named like documentContent__<UUID>_fileContent, plus some ending in _thumb1024, which by the name are thumbnails. For comparison, the whole ~/Library/Mobile Documents directory was 29 GB; in other words, bird's cache was about 70 GB larger than all of iCloud's local data.

The largest file in ClonedFiles was 10.6 GB. It was a ZIP archive modified on October 29, and the first file inside was called 043-69093-778.dmg. Searching the machine for that file name and its exact size turned up nothing. Apart from it, there wasn't a single file over 100 MB; most of the rest were between 53 MB and 56 MB. Counted by month of modification, 3598 of the 3643 files were from October.

Sync status

While I was looking at the cache, bird was using 92.3% CPU, and brctl status showed client:needs-sync. In bird's log, EINTR: client gather phase was invalidated appeared 8 times between 11:48:28 and 11:48:39, along with cancelled downloads:

1
bird[435] [com.apple.cloudkit:OP] Finished operation <BRFetchRecordsOperation: …, shortened-name=Download (user initiated) }, …, stateFlags=executing|cancelled, <private>>  with error: <CKError 0x7fd4d8674890: "Operation Cancelled" (20); …>

I didn't do anything to bird. When I checked again a dozen or so minutes later, bird's CPU usage was 0.0%, and brctl status had changed to client:idle.

Files kept downloaded

I had set "Keep Downloaded" on a few items in iCloud Drive, and the cleanup must not touch them. This setting is stored in an extended attribute named com.apple.fileprovider.pinned#PX. Note that the trailing #PX is part of the name; xattr -p com.apple.fileprovider.pinned reports No such xattr, so match it with grep instead:

1
2
D=~/Library/Mobile\ Documents/com~apple~CloudDocs/<some directory>
for f in "$D"/*; do xattr "$f" | grep -q fileprovider.pinned && echo "$f"; done

Four items had this attribute: two directories and two script files. The largest directory was 16 GB with 996 files; I'll call it the "pinned directory" below. It lives under Mobile Documents, while the cache to be deleted lives under Caches; they are different directories. To be on the safe side, I checked the pinned directory's file count and du before and after every step.

Deletion

First rename ClonedFiles, and only delete it once everything checks out. A rename can always be undone; a deletion can't.

1
2
3
4
cd ~/Library/Caches/CloudKit/com.apple.bird/<hash>/MMCS
mv ClonedFiles ClonedFiles.pending-delete
# Check the pinned directory and bird's status; delete only if all is well
rm -rf ClonedFiles.pending-delete

After the rename, bird stayed at client:idle and didn't recreate ClonedFiles. Available space was 56 GB before the deletion and 156 GB after. I then deleted a 7.3 GB temporary file left in MMCS, bringing available space to 162 GB. The pinned directory stayed at 996 files and 16 GB throughout.

The 42 GB at the start doesn't match the 56 GB before the deletion because two other things happened in between. First, before touching the cache, I deleted an iPhone backup and a Time Machine local snapshot, which brought available space to 61 GB; snapshots are discussed in the "Prevention" section. Second, around the time of the rename, available space dropped from 61 GB to 56 GB; during the same period, that temporary file grew by about 7 GB, which is explained in the "Causes" section.

Causes

There were actually two things taking up space here: the 101 GB in ClonedFiles, and the temporary file in MMCS that kept growing on its own. They need to be explained separately.

What was in the cache

The file names in the cache are just UUIDs, so they don't reveal what the originals were. The clues are in their sizes and timestamps: 53 MB to 56 MB, mostly from October. So I looked for files of the same size in iCloud Drive:

1
2
# Find 50 MB to 60 MB files in iCloud Drive, including cloud-only ones
mdfind -onlyin ~/Library/Mobile\ Documents 'kMDItemFSSize > 50000000 && kMDItemFSSize < 60000000' | wc -l

There were 3376 in total, 3275 of them in the same photo directory. That directory has a subdirectory holding 2490 Sony RAW photos (.ARW), totaling 135.8 GB according to ls and 0B according to du, i.e. all of them had already been moved off the local disk. Comparing item by item:

  • Size: these ARW files range from 52,129,792 to 56,188,928 bytes. Of the cache files I had sampled that morning, 11 were between 53 MB and 56 MB, and all of their sizes fell within this range
  • Time: these ARW files were all modified between 16:22 and 16:35 on October 19. Of those 11 cache files, 7 had timestamps between 16:28 and 16:33 on October 19; the other 4 were from 12:13 on October 22 and 11:32 and 13:00 on October 29. In the same photo directory, a subdirectory with a few ARW files was added on each of those two days, and one of them was modified at exactly 13:00 on October 29
  • Volume: excluding the 10.6 GB ZIP, the remaining cache was about 90 GB, less than the 136 GB of photos

The cache also contained thumbnails, so the counts can't be matched one to one with the photos, and my sample was only 11 files. Still, since both sizes and timestamps match, most of the content of ClonedFiles was very likely this batch of photos that went into iCloud Drive on October 19.

Why it took up space

The original photos had been moved off the local disk and du reported 0B, so in principle those 136 GB were no longer on disk. Why the cache could still occupy 101 GB, I can only offer a guess that I wasn't able to verify.

Going by the directory name, ClonedFiles holds cloned files. Suppose bird cloned each file before uploading it. Right after cloning, the cache shares data blocks with the original and takes no extra space. Later, "Optimize Mac Storage" moved the originals off the disk, but the clones were still there, so those data blocks now belonged to the clones alone. In Finder, the photos are cloud-only; on disk, the space never came back.

This guess explains two things: the photos had clearly been moved off the disk, yet the space wasn't freed; and the sizes and timestamps of the cache files matched the originals exactly. Unfortunately, by the time this occurred to me the cache had already been deleted, so there was no way to check whether those files had really shared data blocks with the originals.

Also, generally speaking, a file has to be uploaded to the cloud before it can be removed locally. If so, since all of these photos had been moved off the disk, they must all have finished uploading. That means the cache stayed around for at least two more weeks after the uploads finished. I couldn't find out why bird never cleaned it up.

A temporary file that grows

The other thing taking up space was tmpm-0x0000000000001849 under MMCS. Around 11:48 in the morning, ls showed it at 5.2 GB, and it took up almost no space. By 13:05, ls showed 12.5 GB and du 7.3 GB, with a last modification time of 12:20.

After I deleted the whole MMCS directory, bird soon created a new file with the same name. Here is bird's log from that period:

1
2
3
4
13:13:42.745 bird[435] [NOTICE] downloading 1 documents in <private>
13:15:22.478 bird[435] [NOTICE] <private> - finished downloading (cancelled) 1 documents (<private>) in <private>
13:15:22.879 bird[435] [NOTICE] downloading 1 documents in <private>
13:15:52.664 bird[435] [NOTICE] <private> - finished downloading (cancelled) 1 documents (<private>) in <private>

The modification time of tmpm-0x0000000000001849 was exactly 13:15. A few hours later, ls showed it at 12.3 GB and du at 1.1 GB, and its first 48 bytes were all zeros.

From these observations, my guess is that a document of a dozen or so GB was being downloaded over and over. Each attempt wrote part of the data into this temporary file, then got cancelled and started again. The 7 GB of growth in the morning may have been the same thing. From midnight to a little after 13:00 that day, bird had 7 cancelled downloads and 4 completed ones. Which document it was, who initiated the download, and why it kept being cancelled, I couldn't find out: the log only says <private>.

Recognizing the Problem

To sum up what I learned, here is the order in which to check things next time.

First, compare the size of bird's cache with iCloud Drive's local data:

1
2
du -sh ~/Library/Caches/CloudKit/com.apple.bird
du -sh ~/Library/Mobile\ Documents

When the problem was present, the former was 101 GB and the latter 29 GB; a few hours after the cleanup, the former was 1.1 GB. If the cache is larger than iCloud's local data, it's worth digging further. At that point, check how much MMCS/ClonedFiles and MMCS/tmpm-* each take.

If ClonedFiles is large, look for the originals by size and time. First see which days the cache files' modification times cluster on, then look in iCloud Drive for large batches of files added around the same time. A directory that was added recently, has a du of 0, and has files of the same sizes in the cache is the prime suspect.

If tmpm-* is large, check whether bird is downloading something over and over:

1
2
3
4
5
# Cancelled and completed bird downloads in the last hour
log show --last 1h --predicate 'process == "bird" AND eventMessage CONTAINS "finished downloading"' --style compact \
| grep -c cancelled
log show --last 1h --predicate 'process == "bird" AND eventMessage CONTAINS "finished downloading"' --style compact \
| grep -vc cancelled

If the number of cancellations keeps going up while the du of tmpm-* grows, you're looking at the same situation as this one.

Prevention

First, after putting a large batch of files into iCloud Drive at once, wait for the upload to finish and then check bird's cache. This time it was 136 GB of RAW photos added in one go. If the guess above is right, "Optimize Mac Storage" moving the originals off the disk doesn't free up any space at that point; instead, the cache keeps hold of it. The tighter the disk, the more this is worth keeping an eye on.

Second, clean up the cache in order:

  1. brctl status shows client:idle, and bird's CPU usage is close to 0
  2. Find the items with com.apple.fileprovider.pinned#PX, and note their file counts and du
  3. Rename ClonedFiles, then check the pinned items and bird's status
  4. Delete it once everything checks out, and check again

I should point out that, when looking for the "Keep Downloaded" flag this time, I only checked the first level of one directory. brctl dump also still showed some entries marked needs-sync-up, and I didn't check one by one whether they had finished uploading. Nor did I confirm whether the 10.6 GB ZIP archive still exists in the cloud; if it existed only in the cache, it was deleted along with it. Before following these steps, you'd better check these points yourself.

Third, check for local snapshots before cleaning up. APFS local snapshots keep hold of the space used by deleted files. This time, before cleaning the cache, I deleted a 17 GB iPhone backup, and the available space reported by df didn't change; only after deleting the Time Machine local snapshot with tmutil deletelocalsnapshots 2026-11-06-235702 did available space go up from 44 GB to 61 GB. Most of the files in ClonedFiles predated this snapshot, so had the snapshot still been there, deleting them would probably not have freed any space either.

1
tmutil listlocalsnapshots /

As for the download that kept getting cancelled, I have no fix for it yet. The tmpm file is only 1.1 GB right now; for now I'll keep an eye on it periodically with the commands from the previous section.

Link
Plus
Share
Class
Send
Send
Pin
If this post helps you, please consider to buy a cup of coffee for me.