Apple Pro Training Series: OS X Support Essentials 10.10: Supporting and Troubleshooting OS X Yosemite: Application Troubleshooting
From the book
From the book
From the book
Reference 19.4 Application Troubleshooting
Application issues are as diverse as the applications themselves. Just as each application is designed to provide unique features, problems often manifest in unique ways as well. Fortunately, there are a variety of general troubleshooting steps you can take when diagnosing and resolving an application issue.
General Application Troubleshooting
The actions in the following list are in order from the least to the most invasive and time-consuming. Actions are also generally presented according to the likelihood of their success in resolving the issue, from most to least likely. Generally, when troubleshooting applications, start with one of these actions:
- Restart the application—Often, restarting an application resolves the issue, or at least resolves application responsiveness. In some cases, the application may become unresponsive and you may have to forcibly quit it to restart it, as detailed later in “Forcibly Quitting Applications” on page 593.
- Try another known working document—This is an excellent method to determine if a document has become corrupted and that is the cause of the problem. If you discover that the problem’s source is a corrupted document file, usually the best solution is to restore the document from an earlier backup. As covered in Lesson 16 “Time Machine”, OS X includes a sophisticated and easy-to-use backup system.
- Try another application—Many common document types can be opened by multiple Mac applications. Try opening the troublesome document in another application. If this works, save a new “clean” version of the document from the other application.
- Try another user account—Use this method to determine if a user-specific resource file is the cause of the problem. If the application problem doesn’t occur when using another account, search for corrupted application caches, preferences, and resource files in the suspect user’s Library folder. Creating a temporary account to test—and then deleting it—is quite easy, as covered in Lesson 5 “User Accounts”.
- Check diagnostic reports and log files—This is the last information-gathering step to take before you start replacing items. Few applications keep detailed log files; however, every time an application crashes, the OS X diagnostic reporting feature saves a diagnostic report of the crash information. Using the Console application to view diagnostic reports is detailed later in “Viewing Diagnostics via Console” on page 595.
Delete cache files—To increase performance, many applications create cache folders in the /Library/Caches, ~/Library/Caches, and ~/Library/Saved Application State folders. A specific application’s cache folder almost always matches the application’s name. Although not the most likely application resource to cause problems, cache folders can be easily deleted without affecting the user’s information. Once you delete an application’s cache folder, the application creates a new one the next time you open it. One cache type that can’t be removed easily from the Finder are the various font caches. However, the system font caches are cleared during a safe boot, as covered in Lesson 27 “System Troubleshooting”.
- Replace preference files—Corrupted preference files are one of the most likely of all application resources to cause problems, as they change often and are required for the application to function properly. Application preference troubleshooting is detailed later in “Preference Troubleshooting” on page 597.
- Replace application resources—Although corrupted application resources can certainly cause problems, they are the least likely source of problems, since application resources are rarely changed. Application resource troubleshooting is also detailed later in “Application Resource Troubleshooting” on page 602.
Forcibly Quitting Applications
It’s pretty easy to tell when an application becomes unresponsive—it stops reacting to your mouse clicks, and the pointer often changes to a wait cursor (spinning pinwheel) and stays that way for more than a minute. Hence, the terms spinning-wheel and beach-balling have become slang for a frozen Mac application.
Because the forward-most application controls the menu bar, it may seem as if the application has locked you out of the Mac entirely. But moving the cursor from the frozen application window to another application window or the desktop usually returns the pointer to normal—and you can then click another application or the desktop to regain control of your Mac.
OS X provides no less than three methods for forcibly quitting applications from the graphical interface:
- From the Force Quit Applications dialog—Choose Apple menu > Force Quit, or press Command-Option-Escape to open the Force Quit Applications dialog. A frozen application appears with “(not responding)” next to its name. To forcibly quit, select any application and click Force Quit. Note that you can only restart the Finder from this dialog.
- From the Dock—Use secondary (or Control-) click, or hold down the application’s icon in the Dock, to display the application shortcut menu. If the Dock has recognized that the application is frozen, simply choose Force Quit from this menu. Otherwise, hold down the Option key to change the Quit menu command to Force Quit.
- From Activity Monitor—Open /Applications/Utilities/Activity Monitor, and then select the application you want to quit from the process list. Next, click the “X in an octagon” button on the far-left edge of the Activity Monitor toolbar, and then click the Force Quit button. Activity Monitor is the only built-in graphical application that also allows administrative users to quit or forcibly quit any other user process or background system process.
)
Diagnostic Reports
To help diagnose persistent issues, the OS X diagnostic reporting feature springs into action any time an application quits unexpectedly (commonly known as a crash) or stops functioning and you have to forcibly quit it (commonly known as a hang). This process displays a warning dialog that lets the user know a problem has occurred.
More importantly, this process records log files that detail the circumstances surrounding the application’s crash or hang. If you click the Report button when the warning dialog appears, you can see the diagnostic report and, optionally, add comments to send to Apple.
)
Viewing Diagnostics via Console
Even if you don’t send the report to Apple, you can revisit diagnostic reports later, as they are always saved to the system volume. If the problem report was generated by something running for the user, the log is saved to the user’s ~/Library/Logs/DiagnosticReports folder. However, if the problem report was generated by something running as the system, the log is saved in the local /Library/Logs/DiagnosticReports folder.
The easiest way to view these reports is to open the /Applications/Utilities/Console application and then click the Show Log List button in the toolbar. The diagnostic reports are chronologically listed in the Diagnostic and Usage Information section. Each problem report entry is named by the application followed by the date and time in 24-hour notation.
)
These diagnostic report logs include highly technical information that many won’t understand, but they also include key pieces of information that may help the average troubleshooter diagnose the issue. For example, diagnostic reports often indicate which files were being used by the application at the time. One of the reported files could be the source of the problem due to corruption.
Another method in the Console application for reviewing hangs and crashes is to choose File > New System Log Query, which allows you to construct a custom search to precisely target key items across the most common logs.
)
Much like constructing a custom Spotlight search in the Finder (as covered in Lesson 15 “Metadata and Spotlight”), you can click the Add (+) button to add multiple search criteria. Each new search criteria is an “and” by default, but you can define an “or” by holding down the Option key when you click the Add (+) button. For example, the preceding screenshot shows a search that looks for any log sender that contains “crash” or “spin” or any log sender that includes “hang” and does not contain “change” in the message. In this example, because the word hang is contained in the word change, the final condition is necessary to avoid finding log entries with just the word change.
Preference Troubleshooting
Applications primarily access two types of often-changing files when they are in use: the documents for which the application handles viewing or editing, and the preference files that contain all the application’s settings. From an administration perspective, preference files are often more important, as they may contain settings that are required for an application to work properly. For instance, an application’s serial number or registration information is often stored in a preference file.
Preference files can be found in any Library folder, but most application preferences end up in the user’s Library. Application preferences are kept in user home folders because the local Library should only be used for system preferences. More important, this enables each user to have his or her own application settings that do not interfere with other users’ settings. By this logic, it’s clear that if you’re troubleshooting a system process, then you should look for its preferences in the /Library folder.
Most application and system preference files are saved as property list files. The naming scheme for a property list file usually has the unique bundle identifier for the application first, followed by the file type .plist. For example, the Finder preference file is named com.apple.finder.plist. This naming scheme may seem strange at first, but it helps avoid confusion by identifying the software’s developer along with the application itself.
Many applications are still not sandboxed, so they use the default preference folder for standard applications: the ~/Library/Preferences folder. The full path to the Finder preference file is /Users/<username>/Library/Preferences/com.apple.finder.plist, where <username>;is the account name of the user.
)
For sandboxed applications, the preference will be located in either the Containers or Group Containers folder. Specifically these folders are ~/Library/Containers/<BundleID>/Data/Library/Preferences and ~/Library/Group Containers/<BundleID>/Library/Preferences, where <BundleID> is the unique bundle identifier for the application.
For example, the identifier for the Mail application is com.apple.mail. Therefore, for a user with the account name “ladmin,” the full path to the Mail application’s preference file is /Users/ladmin/Library/Containers/com.apple.mail/Data/Library/Preferences/com.apple.mail.plist.
)
Application preference files are a common application resource known historically to cause problems. Because these files can contain both internal application configuration information and user-configured preferences, even if you haven’t changed any preferences, odds are the application is constantly storing new information in this file. It is the only file required by most applications that is regularly being rewritten, so it has the potential to become corrupted.
Apple has worked to make its own applications and the user preference system wary of corrupt preference files. Many applications that use the Apple preference model, including third-party applications, simply recognize the corrupt preference file, ignore it, and create a new one. On the other hand, many other third-party applications use their own proprietary preference models that are not as resilient. In these cases, corrupted preferences typically result in an application that crashes frequently or during startup
Resolving Corrupted Preferences
The most convenient method of isolating a corrupted preference in the latter case is to rename the suspect preference file. If any part of the preference filename is different than expected, the application ignores it and creates a new preference file. So, in the Finder, add an identifier to the end of the suspect preference filename—something like “.bad.” Alternatively, to make the preference file easier to find later, you could simply put a tilde (~) at the beginning of the file’s name, which causes the Finder to put it at the beginning of the file listing when sorted alphabetically.
The preference architecture in OS X is maintained by a background server process known as cfprefsd. To improve performance, this process uses memory caching to store preference information. After you remove a potentially corrupt preference you should restart this process to clear its cache. As covered previously, you can force any process to quit from Activity Monitor. Because cfprefsd should always be running, the system automatically restarts it when you force it to quit. Also, make sure to force only the cfprefsd process owned by the appropriate user to quit.
)
After you have removed the preference file and restarted the cfprefsd process, opening the application or process creates a new preference file based on the code’s defaults. If this resolves the issue and doesn’t remove any irreplaceable settings, go ahead and trash the old preference file; if not, move on to resource troubleshooting.
If you eventually resolve the problem elsewhere, you can then restore the previous settings by deleting the newer preference file and then removing the filename identifier you added to the original preference file. Again, don’t forget to restart the cfprefsd process. The benefit of replacing the previous preference file is that you don’t lose any of the settings or custom configuration saved in the file.
Viewing and Editing Preferences
One of the primary advantages of using the property list file format is that it can generally be understood by humans. During your troubleshooting, you may find it advantageous to verify settings by directly viewing the contents of the configuration property list file. Many applications and processes keep additional settings items in these files and may not have a graphical interface for configuration.
The content of a property list file is formatted as either plain-text Extensible Markup Language (XML) or binary. The XML format is relatively human-readable with normal text interspersed with special text tags that define the data structure for the information. Thus, you can view and attempt to decipher the XML code of plain-text-formatted property list files using any text-reading application.
Binary-encoded files are, on the other hand, only readable using special tools designed to convert the binary code into human-readable format. Fortunately, OS X includes a Quick Look plug-in that allows you to easily view the contents of either type of property list file by simply pressing the Space bar while you have the file selected in the Finder.
)
If you need to edit a property list file, avoid using TextEdit, as it will improperly format any property list file that is saved as a binary. The most complete graphical application from Apple for editing property list files is Xcode. The Xcode application can decode binary property list files, and it enables you to view and edit any property list in an easy-to-read hierarchical format. Again, Xcode is an optional install that can be found on the Mac App Store.
)
Application Resource Troubleshooting
Although it’s rare, corrupted application software and associated nonpreference resources can be a source of application problems. These types of files rarely, if ever, change after the initial application installation, so the likelihood that such a resource is the cause of a problem is low.
However, keep in mind that many applications use other resources from the local and user Library folders, such as fonts, plug-ins, and keychains, as well as items in the Application Support folder. The hard part is locating the suspect resource; once you have, the fix is to simply remove or replace the corrupted resource and restart the application.
Remember that corrupted resources in the user’s home folder Library affect only that user, whereas corrupted resources in the local Library affect all users. Use this fact to narrow your search when looking for a corrupted resource. Further, application and diagnostic report logs, covered earlier in “Viewing Diagnostics via Console” on page 595, may tell you which resources the application was attempting to access when it crashed. Obviously, those resources should be your primary suspects.
If the application exhibits problems with only one user, attempt to locate the specific resource at the root of the problem in the user’s Library folder. Start with the usual suspects; if you find a resource that you think could be causing the problem, move that resource out of the user’s Library folder and restart the application.
If you’ve determined that the application issue is persistent across all user accounts, start by reinstalling or upgrading to the latest version of the application. You will probably find that a newer version of the application is available—one that likely includes bug fixes. At the very least, by reinstalling you replace any potentially corrupted files that are part of the standard application. If you continue to experience problems after reinstalling the application, search through the local Library resources to find and remove or replace the corrupted resource.