iCloud Drive Not Syncing on Mac? Here's the Fix

You save a Numbers spreadsheet to iCloud Drive, switch to your iPad an hour later, and the file isn’t there. Or it shows up on iPhone with the cloud-download icon but tapping it produces “Could not download.” Or your Desktop folder, which you let iCloud manage, suddenly appears empty.

iCloud Drive sync failures break in distinctive ways depending on the cause. Here’s the troubleshooting flow that resolves the vast majority of cases on macOS Sonoma 14 and Sequoia 15.

Step 1: Confirm iCloud Drive is enabled

This sounds patronizing, but iCloud Drive can be disabled per-app, and most users don’t realize it.

System Settings → Apple ID → iCloud → iCloud Drive. Make sure the master toggle is on. Then click “Apps Using iCloud Drive” — confirm the apps you care about (Pages, Numbers, Keynote, third-party apps) have their toggles on.

Also check System Settings → Apple ID → iCloud Drive → “Desktop & Documents Folders” if you depend on that feature. If it got disabled accidentally during an upgrade, your Desktop folder may be empty locally.

Step 2: Check sync status with brctl

Apple’s hidden tool for iCloud Drive diagnostics is brctl. Open Terminal:

brctl status

The output is dense, but key fields:

• “items pending upload” / “items pending download”: should trend toward zero.
• “fault count”: should be zero.
• “container path” entries: each app’s iCloud container.

If “items pending upload” is high and unchanging after 30 minutes, sync is hung. Continue.

brctl log --wait --shorten

This streams the live sync log. You’ll see real activity if bird is doing anything.

Step 3: Check disk space

iCloud Drive needs free local disk to download files (at least temporarily). If your Mac is below ~10% free space, sync fails silently.

Apple menu → About This Mac → More Info → Storage Settings. Free up space if needed.

If your Mac is constantly bumping against full, Sweep can help reclaim a lot in one pass: caches, logs, leftover app data from uninstalled apps, large unused files. On a typical Mac, the first run frees 10-50 GB.

There’s a faster waySweep does the cleanup in seconds — caches, logs, leftover app data, and large stale files. Try Sweep free →

Step 4: Restart bird

bird is the iCloud Drive sync daemon. When it hangs (which happens after upgrades, network changes, or memory pressure), sync stops entirely.

sudo killall bird

launchd will restart it automatically. Wait 60 seconds, run brctl status again, see if the queue moved.

You can also restart the broader CloudKit daemon:

sudo killall cloudd

Step 5: Check iCloud quota

System Settings → Apple ID → iCloud → Manage Account Storage. If you’re at 100%, sync stops. New uploads silently fail. Free up space by:

• Deleting old iCloud Drive files you don’t need.
• Cleaning up large iCloud Mail attachments.
• Removing old Messages backups.
• Disabling iCloud backup of apps you don’t care about.

Or upgrade to iCloud+ with more storage.

Step 6: Sign out and back into iCloud

Stale auth tokens cause silent sync failures. The fix:

System Settings → Apple ID → Sign Out → “Keep a Copy” for everything. After sign-out, restart, then sign back in.

iCloud Drive will rebuild. This can take hours for large libraries but is reliable.

Skip the manual huntSweep finds the cached configs, leftover daemons, and stale prefs across your Mac. Download Sweep free →

Step 7: Reset CloudDocs

iCloud Drive’s local working files live in ~/Library/Application Support/CloudDocs/. If something corrupts there, sync fails reliably.

1. Sign out of iCloud (keep local copies).
2. Quit all apps that touch iCloud Drive.
3. Move ~/Library/Application Support/CloudDocs/ to the desktop.
4. Restart.
5. Sign back into iCloud.

A new CloudDocs folder is created and sync rebuilds from scratch.

Step 8: Check for problem files

Some files break iCloud Drive sync:

• Files larger than 50 GB.
• File names with characters iCloud rejects (some Unicode glyphs).
• Folders with thousands of files (sync per-file is slow).
• .app bundles or .framework bundles dropped into iCloud Drive.
• Symlinks (iCloud Drive sometimes flips on these and stops everything).

If sync got stuck immediately after dropping a particular file in, move that file out and see if sync resumes.

Step 9: Check the network

iCloud Drive uses Apple’s CDN. If your DNS resolves Apple’s CDN to a slow node, sync will be slow:

dig @1.1.1.1 p01-content.icloud.com
dig @8.8.8.8 p01-content.icloud.com

If resolution times differ wildly, your DNS is the issue. Switch DNS in System Settings → Network → Wi-Fi → Details → DNS.

A VPN that routes Mac traffic through a far exit node will also slow iCloud — disconnect it and test.

Step 10: Check for VPN extension residue

Even with no VPN active, leftover VPN system extensions intercept traffic and slow iCloud:

systemextensionsctl list

If you see extensions from VPNs you no longer use, that’s a problem. Drag-to-trash uninstalls of VPN apps don’t remove the system extension. Sweep’s app uninstaller does.

Reclaim what stale apps left behindOld VPN clients leave network extensions and helper tools that block iCloud. Sweep finds them all. Free for macOS →

Step 11: macOS-specific bugs

Apple has shipped iCloud Drive regressions in several macOS releases. Known issues:

• macOS 14.4: Desktop & Documents sync broke for some users; fixed in 14.4.1.
• macOS 14.5: a Mail / iCloud regression; fixed in 14.6.
• macOS 15.0: initial Sequoia release had multiple iCloud Drive issues; fixed in 15.1+.

Update macOS. System Settings → General → Software Update.

Step 12: Pause and resume sync

Sometimes sync just needs a kick. Right-click the iCloud Drive item in Finder sidebar → there’s no pause option in the GUI, but you can pause via Terminal:

defaults write com.apple.bird optimize-storage -bool false
sudo killall bird

Wait, then re-enable:

defaults write com.apple.bird optimize-storage -bool true
sudo killall bird

This forces iCloud Drive to re-evaluate every file’s sync state.

Step 13: Check for too many “optimize storage” requests

If “Optimize Mac Storage” is on, macOS will offload local files to the cloud when disk is tight, leaving placeholders. If you have 200 GB of placeholders and try to download all of them at once, sync chokes.

System Settings → Apple ID → iCloud → iCloud Drive → “Optimize Mac Storage” — if on, files you haven’t accessed recently are cloud-only. They download on demand. Don’t expect your full library to ever be local at once unless you turn this off.

Step 14: Verify on another Mac or iPad

If sync seems broken on one Mac but other devices syncing the same iCloud account work fine, the problem is on that Mac. Continue troubleshooting it locally.

If sync is broken on every device, the issue is your iCloud account or Apple’s servers. Wait, or contact Apple Support.

Step 15: Last resort

In order of escalation:

1. Boot Mac in Safe Mode and test iCloud Drive there.
2. Create a new user on the Mac and sign in with the same iCloud — does it work for that user?
3. Reinstall macOS without erasing data.

If sync works for a new user but not your old one, your user-level iCloud config is corrupt. The fastest fix is to migrate to the new user account permanently, which is annoying but reliable.

Why iCloud Drive sync breaks

The most common triggers in my experience:

• macOS upgrades that reset local sync state.
• Filling iCloud quota without realizing it.
• Filling local disk to <5%.
• VPN extensions left over from old apps.
• A 50+ GB single file dropped into iCloud Drive.
• Sign-in / sign-out cycles that don’t fully complete.

Step 4 (killall bird) and Step 7 (CloudDocs reset) fix the majority of stuck-sync cases. Try those first before doing anything destructive.