Mac Troubleshooting: Our Top Tips

At some point in your IT career, you’ve no doubt spent a good chunk of your time stationed on the help desk, fielding questions from users and helping them troubleshoot their Mac computers. During that Mac troubleshooting, you’ve probably compiled a list of their most common problems, along with your suggested solutions. 

Many members of the Kandji team have been in that same boat, working as Apple admins and troubleshooting Mac problems for users. The only difference is that the people we help these days are admins themselves who work on Apple IT teams. But many of the problems they’re dealing with are the same ones we dealt with in our days on the help desk.

In helping those teams, our support staff has compiled its own list of the troubleshooting tips we suggest most commonly to Mac admins, addressing a variety of problems. We thought it would be helpful to share that list with the Mac admin community to hopefully save you a bit of time—which you can then spend on more strategic work.

The Classics: Restarting, Resetting NVRAM

Whenever something doesn’t work, the first question is often, “Did you restart it?” Your more experienced end-users may have heard it so often that they’ll first say, after describing their problem, “Yes, I tried restarting it.”

Restarting really is the best first step in almost any troubleshooting situation, especially if you suspect a hardware problem. Many things happen on a Mac when it fully powers on. One of the most important from a troubleshooting perspective is the Power-On-Self-Test (POST). The familiar Mac startup chime is the sign of a successful POST. Many software processes also go through first-run checks only during a full startup. LaunchDaemons and/or LaunchAgents get a chance to get a clear start. 

Although a restart can have many benefits, it is not a guaranteed fix. If the problem is intermittent, restarting may temporarily make it go away, only to resurface later. If restarting seems to take care of whatever the problem was, it is still a good practice to ask the user to tell you if the problem crops up again. 

You may need to ask yourself, what’s the purpose of troubleshooting the problem at hand? Is it so the person can make it to a Zoom meeting? Or might there be a bigger issue, and you’re only troubleshooting one part of it? If a restart doesn’t solve the problem, you need to take your troubleshooting a little further. 

There’s another basic step that applies only to Intel-based Mac computers. Nonvolatile random-access memory (NVRAM) is a small amount of memory that the Mac uses to store some settings for quick access. Resetting NVRAM can help with issues related to MDM enrollment, network connectivity, or peripherals. 

To reset NVRAM, you (or the user) should first shut down the Intel-based Mac, then poise your fingers on the Option, Command, P, and R keys. You press the power button and then immediately hold down those keys. Keep holding them down for about 20 seconds, during which time the startup chime may sound, or the Apple logo may appear more than once. For more information, see the Apple support article “Reset NVRAM on Your Mac.”

Check Preferences 

When you first open an app you just installed, it may generate a preference file to store settings and other data. Typically encoded in binary, JSON, or XML format, that data comprises key/value pairs that an app will use to configure itself. These files end in a .plist extension and can be located in several places, most commonly:

• ~/Library/Preferences 
• ~/Library/Containers/BundleID/Data/Preferences 
• ~/Library/Group\ Containers/BundleID/Preferences 
• /Library/Preferences/ 
• /System/Library/Preferences 

That list is not exhaustive, but most preferences are found in those folders.

Preferences are often the source of the problem when an app isn’t working as intended. If you’ve identified a problematic app, it’s standard practice first to quit it, locate its preference file, create a copy of that, move that copy somewhere else (typically the Desktop), and then delete the original. When you quit and reopen the app, it’ll build a fresh new preference file, which may resolve the issue.

If you can confirm that the old preference file was the source of the problem and want to preserve its settings, you can look inside it to see if you can identify the part that wasn’t working correctly. A virtual machine, test Mac, or new user account can come in handy here to compare instances of the same app using different preference files. Once you determine the broken key/value pair, you can use the command-line defaults command to make granular changes. Developer documentation or a working .plist in a test environment are both great resources when troubleshooting this way.   

One last tip: cfprefsd is a process responsible for caching memory preferences. cfprefsd caches old preferences even if you remove a problematic plist file. Normally that results in better performance, but when troubleshooting preferences, be sure to use a three-step process: quit the app, remove the problematic plist file, then kill the cfprefsd process. One way to kill cfprefds is to use Activity Monitor. When you kill or stop the cfprefsd process, you release the currently cached preference so the new settings can take effect.

MDM Communications Problems

If the issue seems to stem from miscommunication between a managed device and your device management solution—perhaps a command not landing or an app not being deployed—there are a few things to check. 

On the MDM side, are all your tokens and certificates up-to-date, or does one of them need to be renewed? The Apple Push Notification Service (APNs) certificate, Automated Device Enrollment (ADE) token, and the Apps and Books server token all need to be renewed annually. And periodically, when Apple releases major updates to operating systems, you need to sign in to Apple Business Manager or Apple School Manager and agree to the updated terms and conditions. (For the rest of this article, we’ll refer to Apple Business Manager, but it applies to Apple School Manager as well).

For information about configuring these certificates and tokens in Kandji, see “Getting Started with Kandji—Setup.” 

When renewing the APNs certificate, it’s vital to make sure that the same Apple ID used to create the certificate is used to renew it. A new Automated Device Enrollment token and a new Apps and Books server token can be downloaded from Apple Business Manager. 

For help with Apple Business Manager, see “Edit a third-party MDM server configuration in Apple Business Manager” and “Manage server tokens in Apple Business Manager.”

For Apple School Manager, see “Edit a third-party MDM server configuration in Apple School Manager” and “Manage server tokens in Apple School Manager.” 

If all your certificates and tokens are up to date, you should check for network issues; something could be blocking MDM traffic. Begin by narrowing the variables. 

If a VPN is involved, try replicating the issue when the Mac is not connected to it. Is there anything else on the network that might be blocking traffic? Is the firewall blocking something? Is there a proxy in the mix? One easy way to check some of this is with the Twocanoes Push Diagnostic app. It can help verify whether or not all necessary Apple services are reachable. If possible, connect to a cellular hotspot to rule out any local network issues. 

If everything you can control is good to go on the network, check on what you can’t control. While rare, Apple services do become unavailable sometimes. You can check for issues on the Apple services status page and the Apple developer system status page.

Troubleshooting Scripts

If you deploy scripts to run on users’ Mac computers, and those scripts aren’t producing the desired results, you can try several things to solve the problem.

First, ensure that any scripts you’re deploying use full paths, following the rubric /binary/path/command. You can get the full path of a binary using the which command in Terminal. To see this in action, open a Terminal window, type which sh, and view the output (which should be /bin/sh).  

Second, if a script operates on the home folder of the currently logged-in user, consider using a variable instead of the tilde (~) shortcut. The tilde signifies the path of the home folder of the currently logged-in user, but some management solutions don’t support it. Set and use a variable such as currentUser and then command substitution to find the currently logged-in user. For example: currentUser=$(stat -f%Su /dev/console) to get the currently logged-in user. For more on that, see our guide to Mac scripting.

Starting from Scratch

If all else fails, you may need to erase the Mac and start over. We recommended this approach if an issue cropped up during Automated Device Enrollment. It’s also standard practice when transferring a Mac from one user to another. Depending on the use case, the hardware, and the installed operating system, there are multiple ways to get a fresh start. 

If you’re troubleshooting a Mac and don’t want to remove its data, the least invasive way to start with a clean slate is to reinstall macOS, which by default, doesn’t erase user data. An OS reinstall is a good route if you suspect a system file has been corrupted. To do so, you’ll boot into recovery mode. For more information on that, see Apple’s support article, “How to reinstall macOS.”

If nothing else has helped and you want to start over completely, you can use the Erase All Content and Settings feature introduced in macOS Monterey. This feature requires the Mac to be either an Intel-based Mac with the Apple T2 Security Chip or a Mac with Apple silicon. Be sure to have a backup of any data on the Mac because this feature completely erases the Mac and returns it to a condition like it was new and out of the box.

There are two ways to use the Erase All Content and Settings feature for an eligible Mac. Locally on the Mac, you can open System Preferences, click the System Preferences menu at the top left of the screen, and choose Erase All Content and Settings. 

The second way to use the Erase All Content and Settings feature is to issue the Erase Device command from your device management solution. This process requires your MDM solution to support Apple’s Bootstrap Token feature and to have a bootstrap token escrowed for the Mac. For more information on Bootstrap Token, see our blog “Changes to SecureToken & Bootstrap Token in Big Sur.” 

If the Mac is in Apple Business Manager and enrolled in an MDM solution, you can check the status of the bootstrap token and, if necessary, upload it using the profiles command. 

First, you can use this command to verify that your MDM solution supports Bootstrap Token and that the bootstrap token is escrowed with your MDM solution: sudo profiles status –type bootstraptoken. The following example output indicates that the MDM solution supports bootstrap token, and the token for the Mac is escrowed in the MDM solution:

Profiles: Bootstrap Token supported on server: YES
Profiles: Bootstrap Token escrowed on server: YES  

If for some reason, the bootstrap token for a Mac is not escrowed in your MDM solution, you can use the following command: sudo profiles install –type bootstraptoken

For more information on how to work with bootstrap tokens, see Apple’s support article, “Use secure token, bootstrap token, and volume ownership in deployments.” For more information on how the Erase Device command works when using Kandji, see “Erase a macOS Device.” 

Suppose the Mac does not meet the hardware requirements for Erase All Content and Settings or cannot access the user environment. In that case, you can still use macOS Recovery to erase the startup disk and then reinstall macOS. There are separate processes based on whether it’s an Intel-based Mac or a Mac with Apple silicon. For an Intel-based Mac, see “Use Disk Utility to erase an Intel-based Mac”; for a Mac with Apple silicon, see “Use Disk Utility to erase a Mac with Apple silicon.”

The Bottom Line

There are countless reasons why a Mac might run into trouble. Start with the Mac itself and work your way out from there, first to its network connections, then to the servers it’s trying to reach until you figure out where the issue is. 

Also, remember why you’re troubleshooting in the first place. Is this a one-off issue or part of a larger problem? Are multiple users experiencing it, or is it limited to a single user? 

While the list above is by no means an exhaustive one, these are some of the best places to start. If these don’t do the trick, remember that you’re part of a vast and generous community of admins. If you haven’t done so, check out the Mac Admins Slack. It has many channels on a wide range of topics. Chances are, if you can’t find the fix there, you can find someone who can help. Of course, if you’re a Kandji customer, we are eager to help you solve the puzzles you encounter.