This post helps troubleshoot Office COM Add-In load failures.  As there can be many factors contributing to the failure, it is necessary that we be methodical when we approach this issue to ensure we haven’t missed anything simple.

 

Before we begin, please note the terminology used in this post: COM Add-In is an Add-in that implements IDTExtensibility2 interface. This can be developed in managed (.NET) as well as unmanaged code.

If this add-in is developed using managed code, it is also referred to as Shared Add-In or managed COM Add-In or managed Add-In.

Note: VSTO (Visual Studio Tools for Office) Add-Ins are different from COM Add-Ins and are loaded using a different loading mechanism. This post does not cover all (it does cover someJ) the steps for troubleshooting VSTO Add-Ins.

 

Scenario

You have a COM Add-In that you have deployed to a target machine and the Add-In does not load. If you go to COM Add-Ins dialog, it shows the add-in as unchecked, and you see an error “Not loaded. A runtime error occurred during the loading of the COM Add-In” when you select the add-in entry. If you check for the LoadBehavior for the Add-In in registry, it has changed from 3 to 2.

 

Troubleshooting steps

There can be several reasons causing the Add-In to not load, you will find below commonly encountered ones.

 

After you try each step and the add-in still doesn’t load, make sure you perform the following before you move to the next step:

1.       Close all instances of the Office application in question. Make sure there is no running instance of the Office application by checking in the task manager.

2.       If your add-in is supposed to be loaded at application startup, look at the LoadBehavior for your Add-In in registry and make sure it is set to 3. This is necessary because, whenever an Add-In load fails, Office disconnects the Add-In (Loadbehavior changes to 2).

 

Steps common to both managed and unmanaged Add-Ins

1.       Make sure your add-in is not listed in the Disabled Items.
When an Add-In causes a critical error in the Office application (crashes the app), it is marked as disabled and Office will not attempt to load it from then on.
In Office 2003 and earlier versions, you can access “Disabled Items” list from: Help menu > About > “Disabled Items”.
In Office 2007, you can access “Disabled Items” list from: Office menu > {Word/Excel/PowerPoint} Options > Under “Manage” select “Disabled Items” and then click Go.
Note that if your Add-in is a Shared Add-In which does not use a COM Shim then you will need to check if mscoree.dll is listed in the “Disabled Items” list. If you find that your Add-In component is listed in the list, enable it and retry.

2.       Make sure there is no error thrown by IDTExtensibility2::OnConnection and IDTExtensibility2::OnStartupComplete event handlers.
You can place the entire content in these event handlers inside a try/catch (or equivalent) error handling block and log the exception.
You should avoid showing a message box from these event handlers, rather write the exception to a file or use Windows API functions like OutputDebugString and use DebugView to look at the messages.
DebugView can be found at:
http://www.microsoft.com/technet/sysinternals/Miscellaneous/DebugView.mspx

 

3.       Make sure all the required dependencies for your Add-In are present on the target machine and we are able to instantiate the COM component. The easiest way to do this would be to create a simple VBS (VB Script) file with just a CreateObject line and run the VBS file:
-------------------
set o = CreateObject(“ProgId”)
-------------------
where, ProgId is the programmatic identifier for the Add-In’s connect class. E.g. : “MyAddIn1.Connect”.

4.       The Antivirus on the system may be blocking the Add-In load. Run latest updates for the Antivirus and retry. If this doesn’t help, disable the Antivirus program completely and retry. Sometimes the Antivirus software also installs additional Office add-in, you may need to disable these additionally by running through the Antivirus control panel (Settings). Here is one such KB article that talks about Norton Antivirus:
How to use Office programs with the Norton AntiVirus Office plug-in
http://support.microsoft.com/kb/329820

5.       There may be a conflict with other add-ins that are being loaded in the Office application. Disable all other Add-Ins except the one in question and retry.
To disable COM Add-Ins, look at the following registry path (assuming it’s a Word Add-In):
HKEY_CURRENT_USER\Software\Microsoft\Office\Word\Addins
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\Word\AddIns
and change the LoadBehavior for each Add-In where the LoadBehavior is “3” (3 = Load on startup + Connected) to “2” (2=Load on startup)

Note: Office 2003 and earlier versions do not show machine level Add-Ins (ones registered under HKEY_LOCAL_MACHINE) in the COM Add-Ins dialog. 
To know more about the different LoadBehavior values, please refer:
How to build an Office 2000 COM add-in in Visual Basic
http://support.microsoft.com/kb/238228

Steps for managed Add-In

1.       Make sure you have the correct version of .NET framework installed.

2.       Make sure you have Office Primary Interop Assemblies (PIAs) installed on the target machine. You can check this by going to the Global Assembly Cache, GAC, (%systemroot%\assembly) and looking for assemblies beginning with “Microsoft.Office”.
Also, make sure that you are referencing the Office PIAs (not Interop Assemblies) in the project references. You can confirm this by looking at the properties for the reference added. They should point to GAC.
To know more about PIAs, please refer:
Primary Interop Assemblies (PIAs) and Interop Assemblies (IAs)
http://msdn2.microsoft.com/en-us/library/aa169585.aspx

3.       Make sure all the required dependencies for your Add-In are present/installed on the target machine. You can enable Fusion logs to detect missing dependencies.
To enable Fusion logs, you can either use the “Assembly Binding Log Viewer” (fuslogvw) .NET framework tool or make registry entries to enable logging. [Please do make appropriate backup before making any registry changes]. Here are the registry entries that need to be made:

a)      Open regedit and browse to “HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Fusion”

b)      Create a DWORD value by name “EnableLog” and set its value to 1.

c)       Create a DWORD value by name “ForceLog” and set its value to 1.

d)      Create a DWORD value by name “LogFailures” and set its value to 1.

e)      Create a String value by name “LogPath” and set its value to “c:\Fusion”

f)       Create the folder “c:\Fusion”

After reproducing the issue, look at each of the files created under “C:\Fusion\ Default \<Application.exe>\” folder. Fix any failures and retry.
To know more about Assembly Binding Log Viewer (fuslogvw), please refer:
Assembly Binding Log Viewer (Fuslogvw.exe)
http://msdn2.microsoft.com/en-us/library/e74a18c4(VS.80).aspx

4.       If the Add-In is developed in .NET 2.0 or later and is being targeted for Office 2003 or earlier versions, make sure you don’t have the .NET Framework lockback policy for Office which prevents Office from loading Framework greater than 1.1. To know more about this, please refer:
You cannot load a .NET Framework 2.0 assembly from Visual Basic for Applications in Word 2003 and earlier versions, or in Excel 2003 and earlier versions
http://support.microsoft.com/kb/948461

Description of the update for Office 2003: November 8, 2005
http://support.microsoft.com/kb/907417

You can also install this fix as part of your setup by installing KB 908002 on your development box and adding this KB as a pre-requisite to your VS setup project:
FIX: Add-ins, smart documents, or smart tags that you create by using Microsoft Visual Studio 2005 do not run in Office
http://support.microsoft.com/kb/908002

5.       Check if you a have an <application>.exe.config file forcing incorrect version of .NET framework to be loaded. Where <application> is the office application executable file name. If you find a file, rename it and retry. E.g. : winword.exe.config, excel.exe.config, powerpnt.exe.config.

 

 

Hope this helps!