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: 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.
- World of Warcraft\Interface\AddOns\CoolMod\CoolMod.toc
- 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
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.
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 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.
- Completely exit the game.
- Delete the entire World of Warcraft\Cache folder.
- Reopen WoW and log back in. If the problem doesn’t happen anymore, then you’re done!
Step 4: Check for error messages
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, and not the long list of installed addons that may appear after it in the dialog box! This information is not useful, and just makes the addon author scroll past a bunch of useless clutter.
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 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 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.
- Log out of your character, or exit the game.
- Find and delete the addon’s saved variables file(s). They will be found in one or both of these locations:
- World of Warcraft\WTF\Account\<AccountName>\SavedVariables\<AddonName>.lua
- World of Warcraft\WTF\Account\<AccountName>\<ServerName>\<CharacterName>\SavedVariables\<AddonName>.lua
- 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 sothey 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!
- What version of the addon are you using?
Give the actual version number. Don’t just say “latest” or “newest”!
- What locale (language) do you play WoW in?
- What is the problem?
What steps will make the problem happen again?
Be specific! The less time the addon’s author has to spend finding the bug, the faster they can start fixing it!
- What is the exact text of the related error message, if any? (Step 4)
- Does the problem happen when all other addons are disabled?
If not, which addon is it conflicting with? (Step 5)
- Does the problem happen with the addon’s default settings? (Step 6)
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 paste2.org 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 imgbox, 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.