This guide will walk you through the steps of troubleshooting a WoW addon.

If you’re experiencing a problem with an addon, troubleshooting will often allow you to fix the problem yourself, without having to wait for someone else to answer your comment, forum post, or bug report.

Even if you can’t fix the problem yourself, troubleshooting is still useful, because it will give you lots of helpful information to include in a bug report. Remember, the more information you can give the addon’s author, the faster they can fix the problem.

Don’t be daunted by the size of this guide. It’s broken down into eight simple steps, and each step not only provides instructions, but also explains why the step is useful. Once you've gone through the steps once or twice, you can skip the explanations, and the guide seems a lot shorter!

Step 1: Is the problem really with the addon?

Sometimes WoW just flakes out and does really weird stuff. This is usually caused by corrupted data in its cache files. Deleting these cache files will force WoW to make new, uncorrupted cache files.

To clear the cache, completely exit WoW, and delete the Cache folder inside your WoW program folder:
World of Warcraft\Cache

Now relaunch WoW and log back in. If the problem doesn’t happen anymore, then you’re already done!

Step 2: Is the addon is installed correctly?

If the addon appears in the in-game addon list (at the character selection screen, press the red “AddOns” button in the lower left corner) then the addon is installed correctly, and you can skip to Step 3.

If the addon does not appear in the addon list, then the problem is on your computer, not in the addon. In order for WoW to find an addon, it must be in a particular place, with a particular arrangement of files and folders. The most common causes of installation problems include extra folders added by some decompression utilities (including the one built into Windows), extra folders included by confused addon authors, and decompression utilities that don’t preserve file paths.

To verify that an addon is correctly installed, find its TOC file.

Correct:

Incorrect:

If the files are in the wrong place, simply moving them to the right place should fix the problem.

Step 3: Is the addon really enabled?

If the in-game addon list shows the addon’s name in gold with a yellow check mark next to it, then the addon is enabled, and you can skip to Step 4.

If there is a silver check mark, or no check mark, click the checkbox until a yellow check mark appears. If the addon’s name is now shown in gold, then the addon is now enabled, and you can skip to Step 4.

If the addon’s name now appears in red, then there is a problem that prevents WoW from loading the addon. Look to the right of the addon’s name for an explanation. The two most common reasons are:

Out of date

This means that the addon hasn’t been updated since the last major WoW patch. In most cases, this does not mean that the addon won’t work. Most patches don’t change anything that affects most addons, so most addons do not need to be updated for every patch.

Solution: Simply enable the “Load out of date addons” option at the top of the addon list. Don’t change the interface number in the addon’s TOC file.

Dependency disabled

This means that the addon depends on another addon, but that other addon isn’t enabled. For example, a Grid plugin depends on Grid, because it can’t load unless Grid is enabled.

Solution: Move the mouse cursor over the addon’s name, look in the tooltip for the names of any other addons it depends on, and then enable those addons.

Step 4: Does the addon have a Load Manager?

Open the addon’s TOC file in Notepad or another plain-text editor. If it does not list a LoadManager, you can skip this step.

If the addon lists a LoadManager, then essentially the addon is telling WoW “don’t load me at login, because this addon will load me later if I’m needed.” An addon might do this to keep itself from being loaded before it’s needed (for example, if you’re not in a battleground, you don’t need a battleground helper addon yet) or to prevent itself from being loaded on some classes (for example, if you’re not a shaman, you don’t need a totem timer addon). The general idea is that addons are only loaded if and when they are actually going to be used.

However, if you have an addon installed that’s listed as a LoadManager for other addons, but it’s not enabled, then none of the addons that list it as a LoadManager will ever be loaded, even if they are enabled.

If the addon lists another addon as a LoadManager, and you have that addon installed, make sure it is enabled.

Step 5: Is there an in-game error message?

By default, WoW does not show addon errors. To enable their display, open the Interface Options window, navigate to the Help panel, and enable the “Display Lua Errors” option. (Lua is the programming language in which addons, and the default UI, are written.) Now log out and back in, and try to reproduce the problem. When it happens, you might see a dialog box appear on the screen containing an error message. Copy the full text of the error message, and paste it in your bug report.

Please note that you should copy only the error message, not the list of local variables or the list of installed addons which sometimes appear after it in the dialog box! In nearly all cases it’s just useless junk that the author has to scroll through when reading your ticket; in the rare event that the author wants this information, (s)he will ask for it.

Step 6: Does the problem happen with other addons disabled?

This is important because addons can interfere with each other if they try to do the same thing, or if they interact with the same part of Blizzard’s code in ways that each other’s author didn’t expect. Log out and disable all addons except the one you’re troubleshooting. If the addon has any dependencies (identified in Step 3) or a LoadManager (identified in Step 4), enable those too. Now log back in. If the problem still happens, skip the rest of this step.

If the problem doesn’t happen anymore, though, you’ll need to do a little more detective work to find out which addon it’s conflicting with. The quickest way to do this is called a “binary search”.

Enable half of your addons and log in. If the problem doesn’t happen, log out, disable the enabled addons, and enable the other half of your addons. Once you find the half with the problem, disable half of those. Repeat this process until you’re left with a single addon that seems to trigger the problem when enabled alongside the addon you’re troubleshooting.

Step 7: Does the problem happen with the addon’s default settings?

You will need to log out of WoW before proceeding with this step. Simply logging out of your character is enough; you don’t need to log out of your account or completely exit WoW.

Each addon saves its settings in a separate file. Depending on the addon, this file may be shared between all characters on your account, or there may be one file for each character, or there may be both a shared file and character-specific files.

Saved variables that are shared between all characters are located in:
World of Warcraft\WTF\Account\<AccountName>\SavedVariables\<AddonName>.lua

Saved variables that are specific to one character are located in:
World of Warcraft\WTF\Account\<AccountName>\<ServerName>\<CharacterName>\SavedVariables\<AddonName>.lua

If the addon stores a lot of data (like Auctioneer or LootLink) or takes a long time to customize (like kgPanels or PowerAuras), you should back up the file(s) to another location before deleting it, so you can restore it/them later if it turns out not to be the problem. Otherwise, just delete it/them.

Now log back in. If the problem doesn’t happen anymore, then it was probably caused by bad data in your settings file. At this point, you should usually just reconfigure the addon from its default settings.

However, if the problem reappears after you reconfigure the addon, or if your configuration was very complex, you can send your settings file(s) the addon’s author, along with a description of any settings you think are causing the problem, and they can try to figure out what the specific problem is, and whether they can do anything to fix it.

Step 8: Report the problem!

Once you’ve gone through the above steps, you should report the problem to the addon’s author so he or she can fix it. Be sure to include all the information you can. Feel free to copy the list below and use it as a template for your report!

If the problem doesn’t happen with the addon’s default settings, attaching your saved variables file(s) is helpful. If the addon’s ticket tracker doesn’t support file attachments, you can copy and paste the contents of your saved variables file(s) to a pastebin service like paste.wowace.com or gist.github.com, and include a link to it in your ticket.

If the problem is graphical (eg. something on the screen looks wrong), attaching a screenshot is helpful. If the addon’s ticket tracking system doesn’t support attachments, you can upload the file or screenshot to an image-hosting service like imgur or minus, and include a link to it in the ticket.

Remember to check on your bug report after a few days. The addon’s author may need more information from you in order to identify or fix the problem, or they may not be able to reproduce the problem themselves and ask you to try a possible solution.