Fixing Problems with iCloud Desktop and Documents Syncing in macOS Sierra


If you’ve followed the launch of macOS Sierra, you may have heard that iCloud Desktop and Documents syncing is one of the OS’s new features. This feature syncs your Mac’s Desktop and Documents folders to iCloud, making the files available on all Macs and iOS devices connected to that iCloud account. This is neat, but reports have surfaced of some users losing (or thinking they’ve lost) data after enabling the feature. Ambiguity about how the feature works and a poor user interface are to blame, but fortunately the problems aren’t too hard to fix.

The biggest problem really is the UI. The on/off switch for iCloud Desktop and Documents is just a regular iCloud toggle. Historically, those checkboxes haven’t been very clear. When you turn one off, you’ll see a warning about removing data, of course. However, it’s not always crystal clear where the data is being removed from. If this is a pain for Contacts, you can imagine the frustration that arises when the same UI is used to sync what are probably your two most important folders.


However, this feature could be awesome. If you have multiple Macs, you don’t have to use Dropbox, a server or network file sharing to sync files wirelessly between machines. Instead, you can transparently sync your Desktop and Documents folders in the background. You’ll also be able to access your files over iOS devices, as well as through So, backup and broad availability: what an awesome pair!


Unfortunately, iCloud has not always been reliable or even predictable. The underlying architecture is sort of a black box. This makes it hard to figure out when syncing occurs, what data gets overwritten, and how conflicting files are managed. Changes have been made, and more are surely coming, but it’s not the kind of rock-solid system users might hope for.

Where’s My Stuff?

The first time you turn on iCloud Desktop and Documents on a Mac, all your files will stay put. Each item will sync to iCloud, and all will be right with the world. Problems begin to arise when you turn on syncing for the next machine.

On this second machine, macOS instantly takes the files on your local Desktop and dumps them, unceremoniously, into a different folder. That folder will be called something like “Desktop – Steve’s MacBook Pro,” and you can find it on your Desktop. A lot of users haven’t realized this is happening. You can imagine the panicked reactions when greeted with a seemingly-empty Desktop. It might seem like iCloud has replaced your existing Desktop with the “canonical” iCloud Desktop, but it hasn’t. You’re files are still there, just moved a bit. The fix is easy: move your files from that new folder out to your Desktop again.

This idea does help avoid accidental overwrites, but it’s not behavior that any user would expect. A dialogue box would probably make this problem go away immediately.

Why Did My Folders Move?


You might have noticed that your Desktop and Documents folders aren’t where they used to be. After turning on the feature, both folders are moved to the iCloud section of the Finder sidebar. You’ll no longer see them in the Favorites section, or under your user directory. This emphasized the existence of the files as “outside” of your system, but there’s no indication that this has happened. Instead, you’ll find the files at their new home: ~/Library/Mobile Documents/com~apple~CloudDocs/Desktop or /Documents. Note that the folders are symbolically linked to the older directory locations. As such, apps and command-line users can still access their files at the home folder paths, but the actual bits are elsewhere.

What If I Turn It Off?


Turning the thing off is also confounded by a vague dialogue box. Typically, when you turn off an iCloud service, all the records that iCloud had synced to your machine are deleted. So, if you turn off Desktop and Documents sync, does that mean iCloud nukes your Desktop and Documents folders? Yes, but only on that machine.

This does actually make sense within the world of iCloud. But it’s probably not what most users are expecting. macOS will tell you where to find your files: you’ll still see them in iCloud Drive, and you can manually download them back to your now-restored-yet-empty folders at ~/Desktop and ~/Documents.

Big warning: if you turned off iCloud sync while documents on your local drive were not completely uploaded, those files might just vanish. You might find versions in ~/Library/Mobile Documents/com~apple~CloudDocs, but no promises. So beware.

Conclusion: Be Careful

It seems like iCloud Desktop and Documents isn’t quite perfect yet. The biggest problems seems to be unclear implementation and a vague UI. Before turning it on, make sure to back up. Don’t become a victim of iCloud’s voodoo.

Alexander Fox Alexander Fox

Alexander Fox is a tech and science writer based in Philadelphia, PA with one cat, three Macs and more USB cables than he could ever use.


  1. I’m having an issues with the upload taking a few days. The up arrows next to all my files on my desktop are there or they randomly say that it’s still “waiting to upload”. It’s been days with no movement. Any suggestions on how to push through this?

    1. Hi Nils! It sounds like something is stuck between you and the iCloud servers. This is a hard feature to troubleshoot, since it lacks a real interface. Apart from the really obvious stuff (make sure you’re signed into the correct account, you’re connected to a stable network, restart everything, yadda yadda) I’ve heard of people running into problems by not having enough iCloud storage for all their files. This tends to freeze the whole upload process, and the system doesn’t provide a warning reliably.

      If that’s not the problem, I would double-check to make sure your iCloud account is working in general, and that you can save files from this computer to iCloud Drive. I would also check via, which will show you which of your files have successfully uploaded, if any, and hopefully give you more information that a couple of status icons.

      Hope that helps!

    2. I have exactly the same problem. It’s been like this for at least a month now. Nothing uploads to iCloud and when I click on the little icon to the right of “Documents” it shows 504.9 Megs of 34.6 Gigs has uploaded, with a small progress bar under it. Every additional document I save doesn’t upload. I have 1 TB of cloud storage and have only used about 1 Gig of that. I can’t just try switching it off and on again in System Preferences, as I believe that every document which has not yet uploaded will be deleted. That’s a guess of course, as I can’t find any real documentation on this feature! Any ideas of what I can do? This “seamless” option which was supposed to make life easier has completely failed for me!

  2. I enabled desktop and document syncing on my sierra iMac and it moved all my desktop files into a folder named Desktop – xxx’s iMac. I didn’t want them in a separate folder. That’s why I had them on my desktop! I took the files out of that folder and put them back on the desktop then deleted the Desktop – xxx’s iMac folder. Can’t remember what else I did but it has all been going swimmingly with my desktop files where they’re supposed to be and on the iCloud Drive they are in a folder named Desktop – xxx’s iMac. Today I updated my laptop to Sierra and all my iMac desktop files filled my laptop desktop and all my laptop desktop files were moved to a folder named Desktop – xxx’s MacBook. It should be the other way around as far as I’m concerned. Any ideas how to fix?

Comments are closed.