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. This guide will walk you through the process.

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

Don’t be daunted by the size of this guide. It’s broken down into seven 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: Check the installation path

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 already installed correctly, and you can skip to the next step.

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 novice addon authors, and (de)compression utilities that don’t preserve file paths.

To verify that an addon is correctly installed, find its TOC file. If the files are in the wrong place, simply moving them to the right place should fix the problem.

Correct:

Incorrect:

Step 2: Check the enabled state

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.

A note about AddonLoader

If you do not have AddonLoader installed, you can skip to Step 3.

Addons can designate other addons as a load manager. This means that if the designated addon isn't installed, then the addon will load normally, but if it is, then the addon won't load until the other addon explicitly asks it to. For example, if you use Postal and AddonLoader together, then Postal won't load until you actually visit a mailbox. This can speed up the loading screen you see while logging in -- though most of that time will be lost right after the loading screen, as all the addons that use the generic "delay" instruction are loaded as soon as it disappears.

The system has a serious flaw, though -- if you have a load manager installed, and disable it, then all the addons that designate it as their load manager will completely fail to load. In this way, if you install AddonLoader, then it becomes a required dependency for all addons that designate it as a load manager. Keep this in mind when proceeding with debugging.

Recommendation: Do not install AddonLoader unless you have a good understanding of how it works and a strong reason to use it. Personally, I find no compelling reason to use it, even though I have about 200 addons installed. The post-loading screen freezes are more annoying than seeing the loading screen for an extra second or two.

Step 3: Clear the cache

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.

  1. Completely exit the game.
  2. Delete the entire World of Warcraft\Cache folder.
  3. Reopen WoW and log back in. If the problem doesn’t happen anymore, then you’re done!

Step 4: Check for error messages

Unfortunately, WoW does not show error messages that happen in addon code, but these messages are invaluable to addon authors when trying to track down the cause of a problem. To see them, you’ll need to install an error-catching addon. I recommend Bugger (which I wrote); two other popular options are BugSack and Swatter.

After installing the error-catching addon, restart WoW and try to reproduce the original problem. When it happens, the error-catching addon's minimap icon (or icon on your DataBroker display if you're using one) will turn red if any errors were detected.

Click the icon to open a window showing the full text of the error message. If there is more than one error message, click the "previous" button until you get to the first error message; usually, all the other ones are the result of the first error, and don't actually provide any insight into the problem.

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, and not the long lists of extra items — often labeled locals, local variables, or installed addons — that may appear after it in the dialog box! This information is not useful in the overwhelming majority of cases, and just makes everyone who looks at your report waste time scrolling past it.

Step 5: Check for addon conflicts

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 2) or a LoadManager (identified in Step 2b), 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 6: Try the default settings

While some addons may offer an in-game “reset” option, it’s best to completely remove its saved settings and let it start from scratch. Back up your existing settings files first, so you can restore them later if the problem turns out to be unrelated to your settings.

  1. Log out of your character, or exit the game.
  2. Find and delete the addon’s saved variables file(s). They are located in one or both of these locations in your account folder:
    World of Warcraft\WTF\Account\<Account>
    • SavedVariables\<AddonName>.lua
    • <Server>\<Character>\SavedVariables\<Addon>.lua
  3. Log back into WoW.

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 and you'd prefer not to have to set it up all over again, 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 7: Report the problem

Once you’ve gone through the above steps, you should report the problem to the addon’s author so they can fix it. Be sure to include as much information as you can — always err on the side of giving too much detail, rather than not enough. Feel free to copy the list below and use it as a template for your report!

If the problem only happens on one character, include that character’s level, class and spec.

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 gist.github.com, and include a link to it in your ticket.

If the problem is graphical (ie. 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, 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.