How To Troubleshoot A Hackintosh

We love building hackintoshes, but seeing as Mac OS X wasn’t exactly made to run on third-party hardware you’re bound to run into problems now and again. When you do, here’s how to deal with them.

Troubleshooting a hackintosh generally involves a lot of trial and error, many surprises, and plenty of frustration. This guide seeks to take away a little of that frustration by helping you 1) deal with some common issues, 2) figure out issues not discussed here, 3) find people to help you out when you’re stuck. We’ll help you out with a bunch of examples, but what you want to take away from this guide is how the solutions were found and not so much what they are. At some point you’re going to encounter a new issue or one nobody’s discussed online just yet. While you can be the one to start the discussion, you can also be the one to solve the problem yourself and share the solution. This guide aims to get you in the right mindset so you can troubleshoot your issues on your own.

If you’re new to this hackintosh business, however, this troubleshooting guide is probably not the best place to start. Instead, check out our always up-to-date guide to building a hackintosh to learn the process from start to finish.

One more important thing: This guide assumes you’ve built a Hackintosh with compatible hardware. If you’re trying to force an unsupported component into submission, you’re not going to find many answers here. If you’re trying to fix something that should be working, however, read on.

Common Problems

Before we get into more vague troubleshooting strategies, let’s take a look at some common problems and approaches on how to solve them. Chances are your issue will show up in this list. While hackintoshes certainly have a way of seeming capricious, their troubles tend to fall into some common categories.

Kext(s) Won’t Load

If a kext (the shortened version of “kernel extension”) isn’t loading, sometimes you just need to reinstall it. Other times there is a permissions issue and running a permissions repair (either through MultiBeast or Disk Utility) will fix the problem. If none of that works, try the kextload command in the terminal. For example:

sudo -s kextload -v /path/to/some.kext

Also, double-check that you’re not loading a kext that’s conflicting. (Generally this means a kext that does the same thing.) If everything seems to be failing, you may just have a bad kext or one that won’t work with the version of OS X you’re trying to run. Try re-downloading to just make sure the file isn’t corrupt. Look for other versions. Sometimes the latest version isn’t the one you’ll need (although it probably is). If it’s just not working, look for alternative kexts that do the same thing. You might be out of luck, but when kexts are supposed to work you can usually get them to do their job with a little effort.

Kext is Causing a Kernel Panic (or Other Unpleasant Problems)

Sometimes kexts that should work cause kernel panics — the OS X equivalent to the blue screen of death — or weird glitches. The bigger problem is that when you install a bunch of kexts to add support for the various components in your new machine, you don’t necessarily know which ones are working and which ones are trying to make your head explode. Sometimes it’s just one kext, and you can figure it out by paying attention to the errors you’re getting. Other times it’s multiple kexts, which makes the troubleshooting process much harder as you can remove one of the problem kexts and still see the issue rear its ugly head. First things first, boot into verbose mode (enter -v as a boot flag when booting up) to see if you can find the conflict that way. If not, thee best way to solve the problem is by isolating it through trial and error.

You may want to simply start removing kexts you installed until you find the problem, but if you have multiple conflicts that’s an easy way to miss the problem. You’re better off wiping out all your installed kexts and re-installing them one by one, running a permissions repair and maintenance scripts after every kext. This way you’ll know as soon as you install the problem extension. If you get a little kext happy and install some things you might not need, you might find the conflict is something you can easily remove. If it’s something you actually need for your system to function properly, however, you have a relatively complex issue on your hands — assuming the kext is known to work on your hardware, that is. If you can’t remove it or try an alternative, you may have some sort of conflict in your BIOS. If not, it’s probably time to start posting on hackintosh forums in hopes of finding an answer. We’ll discuss both of these things a little bit later in this guide.

GraphicsEnabler Won’t Work

GraphicsEnabler is a piece of the Chameleon/Chimera bootloader — the thing that actually lets your hackintosh boot to a Mac OS X installation — that enables many Apple-supported graphic cards to work without much configuration. In theory, all you have to do is enabled GraphicsEnabler and you’re done. Reality, on the other hand, can sometimes be a little different because not all versions of a graphics card work exactly the same way. On the upside, fixing a GraphicsEnabler issues is generally pretty simple.

First things first, Check tonymacx86’s graphics card database. Some cards require you add a DeviceID string to their driver in order to work properly. This sounds kind of daunting, but it’s not. You just right-click the kext you want to edit, open the info.plist file inside of it, and change the existing DeviceID to your card. (More detailed instructions here.) In most cases, this will fix the problem.

When you’re using integrated graphics, however, you’ll sometimes run into stranger issues. For example, with the Intel HD3000 that’s part of some Sandy Bridge processors, you have some very specific limitations. The amount of RAM in your system can actually have a major impact. Some motherboards only allow the HD3000 to access up to 480MB of the system’s RAM, for example, but Mac OS X sets the limit at 512MB when more than 4GB of RAM is installed. We’re not going to get into the details here, but when these numbers don’t match up it creates a problem that renders graphics performance so slow it’ll take minutes to open a file or application. The solution, in this case, is to only use 4GB of RAM or perform a little complex editing to allow the use of more (InsanelyMac had a post on this specific issue, but I can’t seem to find it at the moment).

The point is, if an easy fix isn’t working you should look for information that doesn’t match up. If Mac OS X is reporting something differently from what’s been set in the BIOS, there’s a decent chance your issue is related to that discrepancy.

You’re Using the Wrong Pre-Edited DSDT

If you know your motherboard it may seem difficult to make the mistake of using the wrong DSDT, but when you’re grabbing a pre-edited file from tonymacx86’s DSDT database you might accidentally grab the wrong one and not realise it. Sometimes it’s something as stupid as click the wrong link and not paying attention to the filename. Other times you’ll have your motherboard’s firmware version wrong and need to download the DSDT file for the correct version. Generally this is not a mistake you’ll make, but it does happen. If you’re downloading a pre-edited DSDT file, always check its name with the name of your motherboard and your motherboard’s firmware version. If they match up, you’re good. If they don’t, try again!

Incorrect BIOS Settings

Often times your hackintosh will not run properly — or at all — if there are conflicts in your BIOS settings. We detail the most important ones in our always up-to-date guide, so be sure to check you’ve followed those instructions correctly. If you’re still having problems, it’s probably time to move on to the next section because your issue may be unique.

Hardware Issues

Sometimes it’s not your fault. Sometimes you have crappy hardware. It’s hard to tell with a hackintosh because it’s easier to assume you did something wrong. The best/quickest way to find out if there’s a problem is to boot to a Linux Live CD and see if the hardware works or not. If it does, get back to the drawing board. If it doesn’t, return the broken part to the store for something that actually functions.

Unique Problems

When you get stuck with a problem that makes absolutely no sense, seems completely unique to you, and nothing even remotely related shows up in a web search, it’s time to take your problem to other hackintoshers on the internet. Two of the best places to ask questions are the InsanelyMac and tonymacx86 forums. The important thing to remember is to always search the forums for your problem before posting and do your best to choose the right subforum for your topic. If your probably is commonly discussed and you don’t bother to look for an existing solution first, you might end up annoying other users and they won’t want to help you. You won’t always find everything that’s happened in the past, but a concerted effort to look before you post is always appreciated.

Alternatively, when the internet turns out to be particularly unhelpful or you’re simply impatient, try talking out the problem with a friend. It doesn’t matter if they’re hackintosh-illiterate or not. Simply explaining the problem and suggesting possible reasons why it might be happening can lead you to a solution. If it does, be sure to take your friend out for a drink for listening to you talk nonsense at them for 30 minutes. Also, post it online. If you’re having a particular problem, there’s a good chance you’re not the only one. Get the information out and help your fellow hackintoshers avoid the same frustration you encountered.