Every few months my iCloud Drive just stops. Finder shows the little spinning sync arrows next to a folder and they never go away. Battery drains faster than it should. And if I open Activity Monitor, there it is: a process called bird sitting at 100% CPU, sometimes with fileproviderd right next to it, both grinding away on nothing.
If you’ve hit this, you already know Apple’s official advice (“sign out and back in”, “toggle iCloud Drive off”) is a coin flip that can make things worse. Here’s the actual fix, from least invasive to most, and how to figure out which one you need.
First, What Is bird?
bird is the macOS daemon that syncs iCloud Drive. (The name is a pun - it’s the “brd” in “iCloud Drive”, and it handles the Documents provider.) fileproviderd is the newer File Provider framework that sits in front of it. When either pegs a core and stays there, it almost always means the sync queue has more work than it can drain - or the queue itself is corrupt.
The trick is telling those two cases apart before you start deleting things.
Step 1: Diagnose the Backlog
There’s an undocumented but stable command-line tool for this: brctl (the “bird control” utility). The status subcommand dumps the current sync state:
brctl status
That output is verbose. The number you actually care about is how many items are queued to upload:
brctl status 2>/dev/null | grep -c needs-sync-up
If that number is small (single or low double digits) and slowly ticking down, you’re just watching a normal sync - be patient, plug in, and let it finish. If it’s in the thousands or tens of thousands and not moving, something is wrong.
While you’re here, confirm the CPU culprit:
ps aux | grep -iE "[b]ird|[f]ileproviderd"
(The bracket around the first letter is a small trick to keep grep from matching its own process.)
Step 2: The Two-Minute Fix (Transient Hang)
If the backlog is small but the daemon is stuck, the problem is usually just a wedged in-memory state, not the data. Both daemons relaunch automatically the instant you kill them, so this is safe:
killall bird
killall fileproviderd
Give it thirty seconds. If CPU settles and the spinner clears, you’re done - that was a transient hang and you never needed anything heavier.
If it immediately re-pegs and the backlog is still huge, the queue itself is poisoned. Move on to the reset.
Step 3: The Full Reset (Corrupt or Bloated Queue)
The local sync state - the database of what’s uploaded, what’s pending, and what the server thinks you have - lives here:
~/Library/Application Support/CloudDocs/session/db
The fix is to move that directory aside and let bird rebuild it from the server’s copy of the truth. Because your files are already on Apple’s servers, this is reversible and non-destructive: you’re throwing away the local bookkeeping, not the documents.
Two things to know before you run it:
- This folder is TCC-protected. Your terminal needs Full Disk Access (System Settings → Privacy & Security → Full Disk Access → add Terminal or iTerm). Without it you’ll get
Operation not permitted. A sandboxed shell - including anything an automation tool runs for you - simply can’t touch it; you have to do this one yourself. - Keep the backup until you’re sure. We rename rather than delete so you can roll back.
DB=~/Library/Application\ Support/CloudDocs/session/db
killall bird
mv "$DB" ~/Desktop/CloudDocs-db-backup-$(date +%Y%m%d-%H%M%S)
bird relaunches, sees no local session database, and rebuilds it by reconciling against the server. Within a minute or two:
brctl status 2>/dev/null | grep -c needs-sync-up
should collapse to roughly zero. When this last bit me, on 2026-06-13, the client.db inside that folder was holding 113,000 orphaned upload entries - queued attempts to upload files that no longer existed - and had ballooned to 2.1 GB. I had moved my development tree out of iCloud two days earlier, on 2026-06-11, but bird was still grinding through a queue full of ghosts of the deleted paths. The reset cleared all 113,000 in one pass; the needs-sync-up count dropped from tens of thousands to zero within about a minute, and iCloud has been quiet since.
Once everything looks stable for a day, delete the backup - it’s gigabytes, and if you leave it sitting on your Desktop inside an iCloud-synced folder, you’ll just re-upload the whole thing. To roll back instead, move it back to session/db.
Why This Keeps Happening (And How to Stop It)
Here’s the part Apple won’t tell you: nine times out of ten, the backlog isn’t your documents. It’s developer artifacts that should never have been in iCloud in the first place.
When your Desktop or Documents folder is synced and you drop a project in there, iCloud dutifully tries to upload every single file inside it - including the tens of thousands of tiny, constantly-churning files that build tools generate. In my case the specific offenders were:
__pycache__/directories and Python.venv/folders, regenerated on every run.terraform/providers/- hundreds of MB of provider binaries per project, re-downloaded onterraform init- Go build and module caches, and Rust
target/directories - Ollama model weights I’d left sitting under a synced folder - multi-GB files iCloud kept trying to push
Each of these is a firehose of small-file churn, and iCloud’s per-file sync overhead means a single terraform init can generate more sync work than a year of actual documents. That’s what poisoned my queue.
The durable fix is to keep code out of iCloud entirely. On 2026-06-11 I moved my whole development tree to a plain ~/Developer directory that iCloud doesn’t sync. The stuck-sync problem hasn’t recurred since - the 2026-06-13 reset above was just clearing the backlog the old synced location had already created. If you must keep projects under Documents, at minimum exclude build directories - though honestly, moving them out is cleaner than fighting the exclusion rules.
The Short Version
- Diagnose:
brctl status | grep -c needs-sync-up. Small and dropping = wait. Huge and stuck = act. - Transient hang:
killall bird fileproviderd, wait 30s. - Corrupt queue: move
~/Library/Application Support/CloudDocs/session/dbaside (needs Full Disk Access), letbirdrebuild from the server. - Prevention: never let iCloud sync your code. Keep dev work in a non-synced directory.
None of this touches your actual files - iCloud is the source of truth, and you’re only ever resetting the local map of what’s been synced. Keep the backup until you’re confident, and you’ve got a clean rollback the whole way through.