iCloud: some explainers

Much of the time, iCloud just works. So long as nothing too horrible happens to your Mac, and your Internet connection continues to function properly, it just ticks away, doing its job.

The trouble with cloud storage is that when things do go wrong, you cannot tell what is wrong or what you can do about it.

One problem is that it uses unfamiliar names, and those names have changed with different versions of OS X.

For example, in OS X 10.9, the daemon handling iCloud Documents was named ubd, and its controller, through which you could look at iCloud problems, was named ubcontrol.

Since then, the main daemon has become known as bird, it is managed by brctl, and the whole system is referred to as CloudDocs.

Now, at least in OS X El Capitan, if you want to run your iCloud diagnostics, you should use a command like
/usr/bin/brctl diagnose --sysdiagnose OUTPATH
where OUTPATH is the path to to a folder which will then contain all the generated output files. Use the --sysdiagnose option if you do not want it to collect information which is already part of the sysdiagnose output, otherwise omit that to get the full diagnostic information.

Furthermore, relevant logs are dispersed. Among those which you can expect to contain useful information about iCloud storage, and CloudDocs, are those in ~/Library/Logs/CloudServices and ~/Library/Logs/Ubiquity.

Folders with the name Ubiquity found in the various Library folders and sub-folders are also about iCloud’s storage, now known as CloudDocs.

If you are having problems with iCloud or CloudDocs in El Capitan, then an early task is to browse the latest log in /var/log/com.apple.clouddocs, where you should find recent warnings and error reports relating to CloudDocs. You should also inspect the two log files in ~/Library/Logs/Ubiquity using Console.

Sometimes, iCloud Data can become inconsistent, and it is better to start from scratch, by emptying the app’s iCloud container. You should only do this if you are confident that you have offline (local) copies of important iCloud documents and data.

For iOS devices, this can be done as follows:

  1. delete the app which creates and handles the data
  2. navigate in the Settings app to iCloud > Storage & Backup > Manage Storage
  3. if the app is not shown in the Documents & Data group, tap Show All
  4. on the Manage Storage screen, tap the app’s name
  5. on the app’s storage info screen, tap Edit, then tap Delete All
  6. when asked to confirm, tap Delete All
  7. wait to allow propagation to other devices.

On a Mac, you can trash the container from the folder with a pathname like ~/Library/Mobile Documents/MyApp, where MyApp is the name of the app. This normally takes you to the app’s folder in iCloud Drive. You should avoid tampering with the app’s files kept in ~/Library/Containers, which store a lot of settings and other data for the app.