How to Fix iCloud Sync Issues on Mac

iCloud Drive sync can break silently. Files get stuck uploading, downloads hang indefinitely, conflicting versions pile up, and macOS gives you almost no visibility into what's happening. I've spent a lot of time debugging these problems, both as a user and while building CloudMonitor, and here's everything I know about fixing them.

1. Check if syncing is actually stuck

The first problem is knowing there's a problem. macOS shows a tiny progress circle in Finder's sidebar, but it tells you nothing about which files are stuck or why.

Open Terminal and run:

brctl status

This shows the current state of the bird daemon, the background process that handles iCloud sync. If you see files listed under "uploading" or "downloading" that have been there for more than a few minutes, they're likely stuck.

With CloudMonitor: The Sync tab shows every active transfer in real time with progress bars, speeds, and automatic stuck-file detection. If a file hasn't made progress in 5 minutes (configurable), it's flagged orange so you can act on it immediately.

2. Restart the bird daemon

The bird process manages all iCloud Drive syncing. When it gets stuck, restarting it often fixes the issue.

killall bird

macOS will automatically relaunch it. Give it 30 seconds and check if your transfers resume. This is the single most effective fix for stuck syncs.

If that doesn't work, also restart the related CloudKit daemon:

killall cloudd

3. Evict and re-download stuck files

If a specific file is stuck downloading, you can force iCloud to start over:

  1. Right-click the file in Finder
  2. Select "Remove Download" to evict the local copy
  3. Double-click the file to re-trigger the download

For stuck uploads, the trick is to move the file out of iCloud Drive, wait for the sync to register, then move it back.

With CloudMonitor: The app can auto-recover stuck files. It evicts and re-downloads stuck downloads automatically, and touches stuck uploads to re-trigger them. You can also manually retry any stuck file with one click.

4. Fix sync conflicts

Sync conflicts happen when the same file is edited on two devices before either change syncs. macOS handles this by keeping both versions, renaming one with a device name and timestamp suffix. The problem is these files are easy to miss, so they pile up quietly.

To find them manually:

find ~/Library/Mobile\ Documents -name "* (*).*" -type f

This searches for the naming pattern macOS uses for conflicted copies. You'll need to manually compare each pair and decide which to keep.

With CloudMonitor: The Sync tab surfaces all conflicts with a red badge. Click into any conflict to see every version: which device saved it, the modification timestamp, and file size. Pick the one you want to keep and CloudMonitor resolves the rest.

5. Reclaim storage space

iCloud sync slows down significantly when your storage is nearly full. If you're above 90% usage, clearing space should be your first step.

To see what's using space, go to System Settings → Apple ID → iCloud → Manage. But this only gives you a high-level breakdown by app. It won't tell you which specific files are eating your quota.

For a file-level view from Terminal:

du -sh ~/Library/Mobile\ Documents/* | sort -rh | head -20

With CloudMonitor: The Storage tab gives you a full breakdown: top folders by size, file type distribution, and a list of your largest iCloud files. It also identifies files you haven't opened in 30+ days that are safe to evict, and calculates exactly how much space you'd reclaim.

6. Find and remove duplicates

Duplicate files are surprisingly common in iCloud Drive, especially after migrations or if you've used multiple sync methods. They waste quota silently.

Finding duplicates from Terminal requires scripting, as there's no built-in tool. A basic approach using file size and name matching:

find ~/Library/Mobile\ Documents -type f -exec basename {} \; | sort | uniq -d

This only finds files with identical names, not content-matched duplicates.

With CloudMonitor: The Duplicates scanner in the Storage tab finds files with matching names and sizes across your entire iCloud Drive. It shows you how much space is wasted, lets you pick which copy to keep, and evicts the rest as cloud-only placeholders, or moves them to trash if you prefer.

7. Sign out and back into iCloud

If nothing else works, the nuclear option: sign out of iCloud entirely and sign back in. This forces a full re-sync.

  1. System Settings → Apple ID → Sign Out
  2. Choose to keep a local copy of your data when prompted
  3. Restart your Mac
  4. Sign back in

Warning: This triggers a full re-upload of your local iCloud Drive contents. On a slow connection with a large library, this can take hours or days. Make sure you have a local backup first.

8. Check Apple's system status

Sometimes it's not you, it's Apple. Before spending an hour debugging, check Apple's System Status page to see if iCloud Drive is experiencing issues.

Prevention

Most iCloud sync issues come from three things: full storage, large files, and editing the same file on multiple devices without waiting for sync. Keep your storage under 80%, avoid putting massive files (500MB+) in iCloud Drive if you can avoid it, and give sync a minute after making changes before switching devices.

Or just run something in your menu bar that tells you what's happening. That's why I built CloudMonitor.

Download CloudMonitor on the Mac App Store →