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.

Subscribe to our newsletter!

Our latest tutorials delivered straight to your inbox