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 a response to a bug report or a forum post. 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 an addon's author, the more likely it is that they will be able to fix the problem, and the less time it will take them to do it.
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!
Occasionally WoW just flakes out and does really weird stuff. This is almost always 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, find the following folder, and delete everything inside of it:
...\World of Warcraft\Cache\WDB\
Now relaunch WoW and log back in. If the problem doesn’t happen anymore, then you’re already done!
If the addon appears in the in-game addon manager (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 manager, 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:
...\World of Warcraft\Interface\AddOns\CoolMod\CoolMod.toc
Incorrect:
...\World of Warcraft\Interface\AddOns\ CoolMod.toc
...\World of Warcraft\Interface\AddOns\CoolMod-v1.3\CoolMod\CoolMod.toc
...\World of Warcraft\Interface\AddOns\Interface\AddOns\CoolMod\CoolMod.toc
If the files are in the wrong place, simply putting them in the right place should fix the problem.
If the in-game addon manager 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:
There are a few other reasons why an addon isn't loadable, but you won't see them very often.
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.
By default, WoW does not show addon errors. To enable their display, open the Interface Options window, navigate to the Help panel, and check 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.
This is important because addons can interfere with each other if they try to do the same thing, or if they interact with Blizzard’s code in unusual ways. 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 3), 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 the procedure until you’re left with a single addon that seems to trigger the problem when enabled alongside the addon you’re troubleshooting.
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 set up, you should back up the file to another location before deleting it, so you can restore it later if it turns out not to be the problem. Otherwise, just delete it. Now log 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 the addon’s settings file(s) the addon’s author, and they can try to figure out what the specific problem is, and whether they can do anything to fix it.
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. If you’re not sure what you should include, 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 is helpful. 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 a file- or image-hosting service, and include the URL 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.