Cloudy with a Chance of Insanity: Unsticking iCloud Drive

With an annual Dropbox renewal looming back in June, I decided to shift all my data from a 2 TB Dropbox family plan (nearly $250 per year) to iCloud Drive. We already had an Apple One Premier plan ($32.95/month) with enough storage for our family’s music and photo libraries, and we were using less than 1 TB of the 2 TB storage. My family barely used Dropbox, and I stored only about 300 GB there. Problem solved, right? I’d save money and consolidate my files.

Just like you shouldn’t brag about light traffic while driving or get a carwash when you think it’s not about to rain, never, never, never say the following words: “iCloud Drive [or any service name] is working great for me, so I’ll just migrate all my data over to it!”

Thus was the beginning of my pain. While I had suffered from iCloud Drive synchronization problems in the past, I have never had such a sustained and resistant issue as over the last five months. That’s right—five months. Worst of all? The problem is now solved, but I don’t know what caused it nor how to avoid it in the future. Apple’s engineering elves fixed it without sending information back through the super senior Apple technical support person I dealt with across many emails, calls, and hours of troubleshooting.

The Mysterious Onset and a Smorgasbord of Solutions

After deciding to switch from Dropbox to iCloud Drive, I moved a few smaller sets of data to test. Those synced to iCloud Drive fine, so I next moved dozens of gigabytes to iCloud. That’s where the problem cropped up—the number of files left to upload remained unchanged after days. 

In my first pass at solving the issue—doing nothing—the problem seemed to self-heal. I assumed it was transient, so I continued my migration, only to see another stall right away. Bafflingly enough, this all happened on my M1 Mac mini; my M1 MacBook Air had no troubles with any iCloud Drive uploads, despite being on the same network. I wound up switching to my MacBook Air for the migration while working out my Mac mini’s problems. (This split between the two machines persisted through the resolution a few days ago.)

I never cracked the nut, which I’ll reveal at the end, but along the way, I learned many iCloud Drive sync resolution tips and received some excellent advice during numerous calls with a senior Apple support technician. (I don’t receive special treatment: I was put into the regular queue, where my first potential savior, Angel, figured out that my problem wasn’t easily resolvable and bumped me up to George, who was a star.)

If you encounter iCloud Drive sync problems, here’s a list of things to try, from least to most disruptive. While testing, you can observe the status of iCloud Drive’s sync in two ways:

• iCloud Drive in the Finder sidebar: A pie-chart icon shows progress; click it to get a file and size progress count, like 3,582 (or 3,582 of 15,384) and 466 MB of 1.2 GB ➊. Display the sidebar by choosing View > Show Sidebar. Show iCloud Drive by choosing Go > Preferences in the Finder and checking iCloud Drive in the Sidebar view.
  
  
• Status bar: While viewing any level of iCloud Drive in a Finder window, the status bar at the bottom ➋ shows the same progress information as clicking the pie-chart icon. If you don’t see it, choose View > Show Status Bar.

On to the troubleshooting!

Try Binary Testing

It’s always worth assuming on a Mac that a single file or folder could be the problem. Back in the pre-OS X days, I had a file that I kept compressed because if it were ever handled in its natural form, it would immediately crash my Mac. I haven’t seen anything as severe since, but because Apple grafted a set of additional permissions onto files at a low level in the filesystem, you may have encountered files you can’t move, delete, or interact with from time to time.

I suggest the old “binary chop” or “binary search,” which is the formal name for splitting something in half repeatedly to find a match. It’s a great way to find a problematic file.

Start by taking half of your folders in iCloud Drive, tagging them with a color to help you remember which you chose, and dragging them onto the desktop or into a local folder. You need to have the storage available for this, as macOS has to download any cloud-only files, which can take some time. If this solves the problem, you’re golden. Drag folders back one at a time until the sync stalls again. When it does, drag the last folder out, open it, and create a parent folder on iCloud to hold half the contents. Repeat recursively until you’ve identified a file that’s the culprit. There might be more than one, but this should at least help you narrow down the candidates.

If moving the first half of your folders doesn’t solve the problem, try the other half, first marking them in a different color for tracking. If moving either half of the folders doesn’t change the syncing behavior, you’ll need to move on to additional troubleshooting.

Bird Is the Word

Little birds live in your Mac, chirping away at iCloud, telling it about all your updates. If only it were that cute. Rather, the bird and cloudddaemons are autonomous, continuously operating programs that monitor for queued items for syncing and perform the necessary data exchanges.

Apple says you should never need to interact with bird. In an ideal world, that’s true! However, when iCloud sync stalls, a simple command often solves the problem. The following Terminal commands force a resync without destroying data.

Type the following command and press Return (as with all subsequent Terminal commands) to restart iCloud synchronization:

killall bird

Before my current migration, that command resolved my syncing problems every time. If that fails, you can escalate with this command, which also restarts cloudd:

killall bird; killall cloudd

If that fails, some people have found that removing a folder of cached iCloud data might also force a resync:

1. Choose Go > Go to Folder (or press Command-Shift-G).
2. Enter ~/Library/Application Support/ and press Return.
3. Drag the CloudDocs folder to the Trash and empty the Trash.

Finally, a few people have found increasing the priority allocated by the system to bird solved their problem. It’s easy, won’t cause system problems, and persists only until the next restart. Enter the following command:

renice -10 -p $(pgrep bird)

Didn’t work? Let’s move on!

iCloud à la Safe Mode

The Apple senior tech I spoke with suggested that I try restarting into Safe mode, which disables all sorts of background items that launch at startup. Safe mode can be a helpful way to figure out if a startup process is causing a problem.

On an Intel-based Mac:

1. Restart your Mac.
2. Immediately hold down the Shift key.
3. When prompted, log in. You may be prompted to log in twice.

An M-series Mac has a different process:

1. Shut down your Mac.
2. When your Mac has powered down, press and hold down the power button until you see a gear icon appear on screen, then release the button.
3. Wait for your startup volume to appear. Single-click it, then hold down the Shift key.
4. Click Continue in Safe Mode.

The words Safe Boot will appear in the menu bar on either the first or second login window with an Intel-based Mac or in the login window for an M-series Mac.

Cache as Cache Can

If that fails, you can also try enabling the content caching server, a suggestion from Howard Oakley, who’s behind the essential Eclectic Light Company blog. The content-caching server lets Apple cache media and iCloud data on your Mac to reduce Internet downloads. The server can be consulted by other devices on your network, too. Here’s how to access the content-caching server:

• In macOS 12 Monterey or earlier, go to System Preferences > Sharing and select Content Caching.
• In macOS 13 Ventura or later, go to System Settings > General > Sharing and click the info ⓘ icon to the right of Content Caching.

You should read this Apple document for all the detailed options. I store the cached files on an external drive as I don’t have enough free space on my startup volume.

Go Nuclear, but Risk Fallout

There’s one last thing that others have suggested: turn iCloud Drive off and back on in System Settings/Preferences > Apple ID > iCloud, but I don’t recommend doing so. Because you’re in an uncertain sync state, when you try to turn iCloud Drive off, Apple prompts you with choices, one of which is to archive the entire state of the drive locally. I chose that option in my debugging process and wound up having to do some tedious rechecking and retrieving from backups because some files that hadn’t synced appeared as 0 KB items in the backup.

None of those options worked for me, so onward we go.

Multihome Is Where the Heart Is

You can imagine I was in a state of despair at this juncture. Because of the many operations I’d performed above, I didn’t feel secure migrating everything back to Dropbox. I felt like I was in a quantum superposition of possible file sync and loss.

Then I hit upon a possible solution that hadn’t turned up in my conversations or searches: I had two active network connections on my Mac mini. Disabling one of those network connections restarted synchronization for a time.

Because I had older Wi-Fi routers and a gigabit Internet connection, I initially connected my Mac mini directly via Ethernet to my primary router to ensure I could always get the best throughput. Later, I upgraded to 802.11ac/Wi-Fi 5 and now 802.11ax/Wi-Fi 6, which can easily hit 1 Gbps. Despite the Ethernet connection, I leave Wi-Fi enabled because Apple requires Wi-Fi for many Continuity features, such as Handoff.

I don’t know why having two networks seemingly caused a problem. So-called multihoming is managed automatically by macOS and has been for many years. If you have multiple routes to local resources and the Internet, macOS automatically sends packets in the most efficient and best way.

My guess was that the combination of two nearly as fast but not identical networking methods, Wi-Fi and Ethernet, coupled with gigabit Ethernet, caused some kind of timing issue. Perhaps some data arrived at slightly different times than the iCloud Drive data center’s servers expected. That shouldn’t matter, but sync resumed as soon as I disabled Wi-Fi and restarted bird again. 

However, my glee was short-lived. In the end, although several gigabytes of files were seemingly subtracted from the remaining total, the process stalled again after a while and wouldn’t restart, no matter how I tweaked my network setup. Curses!

A Rat’s Nest in a Black Box

Apple could have made this easier. Instead of failing continuously and silently, macOS could produce user-friendly errors or provide straightforward logs that could be passed to Apple technical support. Instead, the complexity of iCloud Drive and synchronization is hidden beneath so much detail—as I could see in the logs and using a special bird/cloudd logging tool—that there’s no clarity at all.

My solution ultimately came from perseverance and waiting. I spoke to George multiple times, sometimes two or three times per week and sometimes weeks apart, from May through August. He filed some kind of higher-level ticket that brought a response from engineering with a special profile to install and instructions to follow. With George’s help, I generated gigabytes of diagnostic information and sent them on their way.

I never received unprompted communications from Apple, although George provided follow-up during our process and replied in a cheery and professional manner whenever I checked in. However, sometime in early September, my unsynced iCloud Drive total remaining took a nosedive from about 60 GB to 1 GB. Hurray! It stayed in that range for the next few weeks until 6 October 2023, when I noticed that the message that syncing hadn’t completed had disappeared. When I hovered over the iCloud Drive entry in the Finder, there was the most glorious of all things: a checkmark. I nearly cried. I asked George if I’d ever learn what went wrong and what had to be done to fix it. His reply was… likely not. I concluded that my problem was on a list of things for engineers to debug and fix, but not high up enough to happen right away.

While his problems were different and unrelated, friend and colleague Dan Moren experienced a short-lived and equally unsatisfying black-box iCloud connection issue a few days ago. His outage lasted only (and exactly) 12 hours, but it resolved right around the same time as my multi-month ordeal. My spouse joked that they got Fonzie to whack the serverthat contained Dan’s and my accounts.

Experiences like mine and Dan’s may be rare, but they exemplify what happens when Apple’s “it just works” approach to software fails, leaving users with no ready path forward. I hope this detailed accounting will help others who encounter similar problems. 

I also hope it encourages you to keep calm and soldier on with technical problems when nothing works. Or, rather, stick with it as long as it’s not seriously impacting your productivity and you’re invested in the eventual solution. If iCloud Drive’s failure to sync had prevented me from getting my work done, switching back to Dropbox—however tediously—would have been the smart move. I didn’t lose any data, and I had it all available, if not as conveniently as I would have liked. I’m frustrated at how long my situation remained unresolved and how many hours I had to put into it. Yet, now I’m synced and happy.

Oh, dang. I just said everything worked. Watch this space for inevitable updates.