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!
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
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.
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.
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!
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, and is also the Portuguese word for “moon” — it is not an acronym, and should not be written in all-caps!)
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 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.
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.
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.
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!
- What version of the addon are you using?
Give the actual version number. Don’t just say “latest” or “newest”, even if you've double- and triple-checked that you really are using the latest version. By the time the author reads your report, it might not be the latest anymore, and since it's so easy to be wrong about having the latest version, it's best just to be clear.
- What language and region do you play WoW in?
- What is the problem?
What steps will make the problem happen again?
What do you think should happen?
How is what actually happens different?
Be specific! The less time the addon’s author has to spend finding the bug, the sooner they can start fixing the bug!
- 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.