What to do when iCloud is stuck on uploading items

I use iCloud as my syncing engine for my Obsidian Second Brain, and twice now I’ve seen iCloud get corrupted into a really bad state. I also back up everything to github, so I dont really experience much data loss, but it is annoying to see iCloud be so unreliable at even the simple task of syncing mostly text files.

Today’s issue was that I somehow created some files that iCloud didnt like (I renamed one file, and added a few others, in a short period of time, but nothing crazy), which led to something like this:

and iCloud then refusing to sync anything else that I added or modified to my synced folders from there on out (i was uploading 7kb, not 2gb, which made it even more infuriating that it was getting stuck uploading that trivial of data)

If you google this problem you get a lot of really horrible advice from the apple forums, like turn off your iCloud and on again and again (which deletes stuff that was just fine! if you have a large icloud account - i use mine for photos - that is ~100gb of stuff that just gets wiped and later has to be resynced), or just a depressing chain of black box user anecdotes that don’t offer any confidence whatsoever.

I also tried killing and restarting Finder itself, to no avail.

I’ll skip straight to the point - this is the advice that worked for me.

$ ps aux | grep bird

# output looks something like
swyx               597   1.7  0.1 408320592  38384   ??  S     7:19PM   0:26.45 /System/Library/PrivateFrameworks/CloudDocsDaemon.framework/Versions/A/Support/bird
# grab the process ID (PID) from this output - here it is 597


# optional: Check current priority of bird process
$ ps -fl -C [PID]
  UID   PID  PPID   C STIME   TTY           TIME CMD                     F PRI NI       SZ    RSS WCHAN     S             ADDR
  501   597     1   0  7:19PM ??         0:36.11 /System/Library/  1004004  31  0 408325200  44208 -      R                   0

# Change priority of the bird process
sudo renice -n -10 -p [PID]

once I did this, syncing resumed almost immediately.