For the last week, I have been struggling with my iCloud Photo Library. Sometime after the 12th February it stopped syncing and I don't know why. I have some photos that I took on my Phone that didn't make it to my Mac. They did make it to the cloud and my iPad.
I have googled a lot and tried some stuff. Turn off cloud sync, turn it back on again. Photos will want to compare all 20k+ photos that you have against the cloud but it will get there eventually, in theory, except that it didn't. It got stuck on the last 1500.
Repair the library and it downloads your cloud files for comparison while uploading some files from the Mac. I tried this and it managed to upload the new photos from my Mac to the cloud but got stuck with ~1500 to go, for days.
So I am trying a few things:
I restored a backup of the old library that pre-dates the 12th of February. Things were OK at this point I think. I've put on an external volume and Photos is "doing its stuff" to restore it into something useable. If all goes to plan I'll make this my new System Photos Library and everything will sync to & fro with iCloud.
I took the suggestion of logging out of iCloud and back in again. This I didn't take lightly and for good reason. I use iCloud documents and desktop so everything is shared across all of my Apple devices in the same way as DropBox / Google Drive etc. Except, when you log out of iCloud macOS "wipes" the contents of your shared Desktop and Documents. Not what you would expect and can lead to panic. Log back in and it all comes back slowly. While all your documents are surely still on your machine it re-downloads them from the cloud for comparison, all 26GB of them. Plus all your iCloud Mail, that's another 7GB. Why Apple does this I have no idea, it's stupid. Sure re-sync when you log back in but don't hide the users data from them.
Of course, I took a full image backup of my drive - using SuperDuper - before starting this so I would be OK and could retrieve anything I needed from that. Along with all my other backups too.
Photos is 74% of the way demangling my backup Photos library. The Finder is 50% of the way restoring my Desktop and Documents.
I'm not worried, I have more than enough backups and I know it is all there on iCloud.
Worse case scenario, I start with an empty Photos library and suck everything down, yet again. It will work, but I'd rather not.