Generic troubleshooting: how to fix something that doesn’t work

Over the 25 years or so that I have been answering user questions in various magazines and other publications, there have been some common themes, almost template problems. One goes along the lines of: X used to work (or should work), but does not any more. How can I get it to work again?

This is common in the tools and features which Apple bundles with OS X, in any additions to it, and applications. It is not unusual to be asked to solve this sort of issue in an app which I neither have installed, nor could ever obtain: specialist high-end packages for maths, science, and architecture, for example.

So how would I tackle this, and how do I advise a user?

1. Check that it should work.

Features change, user expectations do not always match features in reality, and there is plenty of scope for misunderstanding. So the first step is always to establish that what the user thinks should happen is actually correct.

El Capitan brought with it a new System Font, San Francisco. Previously, users have expected to be able to use all their installed fonts, including the System Font, in their own documents. However, this time Apple has deliberately hidden San Francisco from font selection dialogs, as it does not want it used except for display purposes. So any user expecting to find it in the font menu in Pages or Word is out of luck.

At this stage I usually check that the user and I are both referring to the latest version of the product. A recent question about failing to get App Store updates, for example, revealed that the user had not had any updates at all since their original upgrade to El Capitan: that upgrade was obviously broken from the start, and was repaired when they re-installed OS X.

2. Search for others with the same problem.

I then phrase searches using Google to locate recent support queries, reports, and any other material germane to the problem. Here the trick lies in selecting the best search terms: if you are looking for information about the VoiceOver feature in the Accessibility pane in El Capitan, you need to combine those key terms, searching for something like “VoiceOver bug El Capitan”, for example.

This is particularly useful when I am answering a question for publication, because a lot of my questioners have already asked in an Apple Support forum, sometimes elsewhere, so I can see what others have suggested. Sometimes a simple search brings me an instant solution in the first few hits, or it may convince me that a lot of users are complaining of the same problem, which has no known solution.

By this stage, I know whether I am on my own in trying to solve the problem, and have to work through the next steps. Sometimes I will have gained some insightful clues which allow me to take shortcuts to the answer, but more often than not it is going to be a sequence of steps like 3-8 below.

3. Check preference settings.

Many applications now have quite labyrinthine panes of preference settings, so they are my next port of call. Sometimes they reveal that the app in question will work the way that the user wants, if they are prepared to switch it to a different display or other mode.

The hidden benefit from checking these out is that it ensures that the preference settings are updated on disk, which is helpful for step 5 below.

4. See if it can be customised using a plugin etc.

If there is no sign of the feature in the app’s preferences, or I cannot get a feature included there to work in the way that it should, my next quest may be to see whether there is another component which will add or fix it. This is particularly appropriate for OS X and the major bundled apps such as Safari, and takes me back to Google and searching online collections of plugins.

I also have a collection of customisation tools, including Deeper, MacPilot, and TinkerTool, which may show that the feature is controlled by a hidden preference setting to which they provide access.

5. Suspect a corrupt preference settings file.

If the feature should be present but does not work, my next suspicion is that the property list file containing the settings has become corrupted or damaged in some way. The stock solution is then to move that file elsewhere, say to ~/Documents, open the app or pane again, and see if the fresh property list then created can fix the problem. This has worked well for a very wide range of settings and features, including most of the panes in System Preferences, and many apps such as Microsoft Word.

In the early days of OS X, this was not difficult, because all the preference settings were stored in the standard Library/Preferences folders, particularly ~/Library/Preferences. Now this has become more tricky, with them being secreted in various other folders. But having just updated those settings in step 3 above, I should be able to tell the current file from those remaining from older installations and versions.

It is also surprising how the name of property lists often reflects the original name for the tool or app in question: for example, main Calendar settings are still stored under iCal, and Contacts are still considered to be the Address Book.

If moving the preference settings does not help, it is best to quit the app, and replace the old settings which were tucked out of the way in ~/Documents, to restore the originals.

6. Suspect a conflicting extension, so try Safe mode.

My next suspicion is that something else, typically a third-party extension of some kind, is blocking the behaviour that the user expects. These may have been carried over in migration from an earlier version of OS X, and can get up to all sorts of mischief.

The best way of eliminating these from the problem is to restart in Safe mode, with the Shift key held down. There may still be a few very persistent things which slip past this, and sometimes Safe mode makes it harder to test whether the problem has gone away, but it is usually helpful.

The problem becomes more complex if it is cured in Safe mode, as there is then the difficult quest to work out which extension or other component is to blame. That can be very tiresome, but a log excerpt following a normal startup often reveals the usual suspects, which are usually such old versions that it is miraculous that anything works properly with them around.

7. Re-install.

If I am still drawing a blank at this stage, and I am confident that the feature should work properly, the next step is to re-install the app or OS X, as appropriate, to see if that fixes the problem. For an app this is not such a big deal, but for OS X most users will have to restart into Recovery mode, waste a long time downloading OS X again, and then waste even more time installing it. Unless the issue is really important, few will want to do that.

8. It’s a bug after all: report and wait.

By this stage, I am running out of good ideas, and it looks increasingly likely that this is a bug. The most important action for any user is to report it as a bug: although they cannot do this for OS X, third-party apps usually have quite a responsive reporting system, even if it may not bring results for a good while. With a bit of luck the next update will suddenly fix the problem, but it may not be mentioned in the release notes.

There are times when I wonder whether this is all worth the effort, but if it means that a user can do what they want, and what they should be able to, that is usually sufficient reward.