Apple - What could cause iCloud Drive to refuse to sync Desktop & Documents?

Looks like the culprit was a circular link at ~/Documents. If this is the case for you, oddly Documents won’t appear at all in your home directory in Finder. However you’ll notice some weird things:

1. That odd empty slot in your Finder Preferences > Sidebar tab (see above)

2. If you try to create a folder called Documents in your home directory, you get a Finder error dialog saying it already exists.

3. If you try to open Documents using Finder > Go > Documents (⇧+⌘+O), you get a Finder error dialog saying it doesn't exist.

Here's the giveaway: run ls -l in your home directory, and look for Documents. Here's what I saw:

lrwxr-xr-x@   1 jacob  staff    22 Jun 11 15:39 Documents -> /Users/jacob/Documents

A quick rm Documents and that was taken care of.

Wait 2 minutes, (apparently some background process has to notice the deletion) then suddenly the Desktop and Documents Folders checkbox under the iCloud PrefPane begins sticking again.

About two hours later (it can take a while) and I saw all my iCloud Drive files being populating my Desktop and Documents in droves.

---

The above, of course, is a bit of a simplification. Because this has been so perplexing I'll say exactly what I did—who knows which of these steps mattered.

1. I actually ran rm -rf ~/Documents (note the -rf flags)
2.  > About This Mac > Storage > Manage…
3. Under Recommendations tab, click Store in iCloud…
4. Check Desktop and Documents
5. Store in iCloud (I believe I recall this also not "sticking" when I pulled up that panel again, but I did it nonetheless)

---

6. Wait 2 minutes. Actually make it 3.

---

7. System Preferences > iCloud > iCloud Drive > Options… > Documents (tab) > check Desktop & Documents Folders
8. This time, it stuck. A few moments later Documents and Desktop showed up under the iCloud section in my Finder sidebar.
9. Wait a long time for it all to sync. Possibly overnight. Files tend to show up in batches, per folder. If you have Optimize Storage on it appears that files under 1MB are downloaded in full while files over 1MB only have metadata downloaded.