Diagnosing and treating Time Machine problems in Terminal

There are only a few things that you can do to try to address Time Machine problems using normal ‘friendly’ tools such as the Time Machine pane in System Preferences. Once you have turned it off and back on again, and restarted, you will probably be running out of ideas.

If your problem is that Time Machine backups are not being started at all, or are only occurring irregularly, then I have explained how you can trace the fault, and given details of the sequence of events which results in a backup being made.

But many problems with Time Machine occur during attempts to back up, when the process aborts with an error message, or, even worse, simply gets stuck and never completes the backup. You can then browse your logs using Consolation or the Terminal command log show, but it can be difficult to recognise what is going wrong, and even tougher to work out how to fix it.

Expert diagnosis

Apple provides a monster of a tool, tmdiagnose, to help its own support engineers work out what is going wrong with Time Machine. It is only accessible from the command line, and when invoked will spend the next few minutes generating a zipped archive of around 290 MB of extracts from logs and much else: it is the Time Machine equivalent of the general sysdiagnose command. It should be invoked in the form
sudo tmdiagnose -f ~/Documents/
which will save the zipped archive into your Documents folder, for example.

What you get is around half a gigabyte of bewildering detail. Here are some pointers:

  • backup_destinations contains a complete analysis of your backups, with the log for each one,
  • backupd-helper.status.txt details current settings for the backupd-helper daemon,
  • brctl contains lots of detailed information about iCloud,
  • there are full diagnostics on Spotlight, because of the role of its metadata in retrieving information from backups,
  • configuration/exclusions.txt contains a useful list of your exclusions from backups, and those set by macOS,
  • [Mac name].mdsdiagnostic/system_logs.archive is a dump of your entire system log which can be read into Console and browsed there. Beware, though – it is very large, normally over 100 MB,
  • logs/install.log is the last macOS update log,
  • logs/oslog.archive is a dump of the entire new-style log which can be read into Console and browsed there. This is even larger, at around 290 MB.

There is a huge amount of information here, most of which is unintelligible to Mac users, and which can readily consume hours of your time. Although the answer will almost certainly be hidden somewhere in those logs and reports, the question is whether you will ever find it among them, or even recognise it if you did see it.

Taking control with tmutil

There is more accessible information, and a full set of controls for Time Machine, in the command line tool tmutil.

To obtain information about backup destinations which are currently configured for Time Machine, use
tmutil destinationinfo
which should return a list, usually containing a single member, such as
Kind : Local
Mount Point : /Volumes/PROMISE PEGASUS
ID : A054C428-7E00-4709-ABB8-38D4E34C400A

To discover the path of the latest backup, use
tmutil latestbackup
This can be useful for confirming location, and the datestamp of that backup.

To see a list of all completed backups, use
tmutil listbackups
which simply lists their paths, with the most recent shown last.

To see the ‘machine directory’, which is the full path to the top level folder of backups, use
tmutil machinedirectory

To force a backup to be run now, use
tmutil startbackup
If you supply the --rotation argument, then backup destination rotation will be allowed during the backup. You can also specify the backup destination with the argument --destination, e.g.
tmutil startbackup --destination A054C428-7E00-4709-ABB8-38D4E34C400A
would force my Mac to start making a backup to the destination listed above, from the destinationinfo verb.

To force a backup which is currently in progress to come to a halt, use
tmutil stopbackup
This may be helpful when a backup is making no further progress, rather than just forcing a restart.

To check the integrity of an existing backup, use
tmsetup verifychecksums [path]
where [path] is the path to an existing backup which you want to check. Checksums are a useful basic check of backup integrity.

You calculate the amount of change between the backups (the ‘drift’) in an individual machine directory with
tmsetup calculatedrift [machinedirectory]
(use tmutil machinedirectory to discover that for use here for [machinedirectory]). This can give you an idea of the space consumption to expect on your backup volume, thus indicate how long it will take for existing space to be used up.

There are three verbs which are useful for dealing with local Time Machine snapshots, which are typically made on laptops when they are away from their full backup drive:
tmutil enablelocal turns local snapshots on,
tmutil disablelocal turns local snapshots off, but does not affect regular Time Machine backups when they are possible,
tmutil snapshot forces a new local snapshot to be made. The first two are required to be run using sudo.

More advanced commands available in tmutil include:

  • tmutil setdestination, which configures a local HFS+ volume, or shared item using AFP or SMB, as a destination for backups;
  • tmutil removedestination, which removes a destination from the list of those used for backups;
  • tmutil addexclusion, which has the same effect as adding a file/folder/volume to the list of items excluded, in the Time Machine pane;
  • tmutil removeexclusion, which has the same effect as removing that file/folder/volume from the list of items excluded, in the Time Machine pane;
  • tmutil isexcluded checks whether an item is on the current exclusion list;
  • tmutil enable turns Time Machine’s automatic backups on;
  • tmutil disable turns Time Machine’s automatic backups off;
  • tmutil compare is a complex command to compare two existing backups;
  • tmutil restore is a complex command which will restore item(s) from an existing backup, much in the way that the Time Machine app can;
  • tmutil delete [path] will delete one or more snapshots or backup stores; use this with extreme care;
  • tmutil uniquesize [path] calculates the physical storage required by a backup, ignoring files which have not changed since the last backup;
  • tmutil inheritbackup allows you to make an existing backup set ‘owned’ by another Mac, the set for your current Mac;
  • tmutil associatedisk allows you to bind a backup volume to the local disk and reconfigure its backup history.

As usual, full and gory details are available using man tmutil.

Although tmutil does not provide any magic wands which will fix all Time Machine problems, it contains many tools which go far beyond anything available in regular apps. Used carefully, it could get your backups out of trouble.