iCloud Files Stuck 'Waiting to Upload' on Mac

iCloud Drive uploads files in a queue, so one problem file can leave everything behind it showing a hollow progress wheel or "waiting to upload" forever. The fix is usually one of five things, and they take about ten minutes to work through in order.

First: is your iCloud storage full?

When your iCloud quota is full, every upload stalls silently. Open System Settings, click your name, then iCloud — the storage bar at the top shows how close you are. If it's full, nothing below will help until you free space or upgrade; deleting old device backups and large files in Manage (or Manage Account Storage) is the fastest win.

Find the file jamming the queue

Open the iCloud Drive section in a Finder window and look for the item whose progress indicator never moves — often a very large file (multi-gigabyte video, disk image) or something a running app still has open. Huge files genuinely take hours on slow upstream connections, so check your upload bandwidth before assuming it's stuck. If the file is open in an app, save and close it so iCloud can read a settled copy.

To watch what the sync engine is actually doing, use Apple's built-in brctl tool:

# live view of iCloud Drive sync activity (Ctrl-C to stop)
brctl log --wait --shorten

If the log keeps retrying the same filename, you've found your culprit.

Reset the connection, then the sync daemon

Two escalating resets clear most stalls:

1. Click the Wi-Fi icon in the menu bar and switch Wi-Fi off, wait ten seconds, and switch it back on. Dropping the network forces iCloud to open a fresh upload session, which often unsticks a wedged transfer.
2. If that fails, restart the sync daemon. Open Activity Monitor (in Applications → Utilities), search for bird — that's iCloud Drive's sync process — select it and click the ⓧ button, then Force Quit.

# same thing from Terminal
killall bird
# no undo needed — macOS relaunches bird automatically within seconds

Restarting bird is safe: it re-scans and resumes the queue from scratch, which is exactly what you want.

The duplicate-and-delete trick for corrupt stragglers

Occasionally one file's sync record gets corrupted and it will never upload, no matter how many restarts you throw at it. Give iCloud a fresh copy to work with:

1. Select the stuck file in Finder and press ⌘D to duplicate it.
2. Confirm the duplicate uploads (its cloud icon disappears once it's synced).
3. Delete the original stuck file and rename the duplicate to the original name.

The copy gets a brand-new sync record, sidestepping whatever was wrong with the old one. If entire folders refuse to move and a restart of the Mac doesn't help, sign out of iCloud (System Settings → your name → Sign Out, keeping copies of everything) and sign back in — the nuclear option, but it rebuilds sync state completely.

When "stuck" is actually just slow

Two situations look like a jam but aren't. First: a brand-new Mac, or a fresh sign-in, kicks off an initial sync of your entire iCloud Drive — that can legitimately run for a day on a big library, and files queue in an order you don't control. Second: home broadband is usually far slower up than down, so a 5 GB video on a 10 Mbps upstream needs over an hour even in perfect conditions. Before force-quitting anything, check Apple's System Status page for an iCloud Drive incident, and if you have the option, plug into Ethernet — sustained uploads are where flaky Wi-Fi shows its true colours.

Know what the icons mean

A hollow wheel, a dotted cloud, and a cloud with an arrow all mean different things — learn to read them in our guide to iCloud file status icons so you can spot a stall before it snowballs.