Troubleshooting COM Add-In load failures


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!

Comments (19)

  1. I have decided to start a series called ‘Troubleshooting Outlook COM Addins’.&#160; I want to outline

  2. We can do further troubleshooting for Add-ins using a Log File and Error Messages as mentioned below:

  3. Joel says:

    Thanks!!  I had this happen on three different machines for three different reasons:  extensibilityMSM.msi needed on one, a disabled FedEx add-in using mscoree on another, and a misnamed MyApp.dll.Config file at one point on my dev machine.  The tip on Fusion logging was a godsend!

  4. Graham says:

    Tried all the steps above and am still having issues (even with a brand new plugin that doesnt do anything in excel). Fusion logging reported no errors for me unfortunately. It really boggles my mind how managed office plugins can be so difficult to deploy and troubleshoot, especially in office 2007 and vs 2008. Kind of reaffirms my opinion that managed code isnt really desktop ready yet (dont get me wrong… I love it on the server).

    Going to have to go back to COM and C for this… not happy about that but at least it works and is backward compatible.

  5. praveenb says:

    Hi Graham,

    Sorry to hear that you are facing problems. If you could give information on any errors that you are facing, may be I could of some help.

    Does creating a new object of your add-in object work?

    ———–

    set o = CreateObject(“ProgId”)

    ———–

    -Praveen

  6. Graham says:

    Thanks for your reply… I tried the VBS script but get an error. Here is the fusion log, I wasnt able to determine any errors from it…accept for possibly this part “A partially-specified assembly bind succeeded from the application directory. Need to re-apply policy.”

    I ran caspol.exe granting full rights on both the dll and manifest files, but still no luck.

    Assembly manager loaded from:  C:WINDOWSMicrosoft.NETFrameworkv2.0.50727mscorwks.dll

    Running under executable  C:Program FilesMicrosoft OfficeOffice12EXCEL.EXE

    — A detailed error log follows.

    === Pre-bind state information ===

    LOG: User = DJXSNBG1Administrator

    LOG: DisplayName = StreamingEdge.ExcelPlatformAdapter

    (Partial)

    LOG: Appbase = file:///C:/Documents and Settings/Administrator/Local Settings/Apps/2.0/0OO8V8EL.56W/1LDVV5JJ.18X/stre..vsto_6da480650dab2fc3_0001.0000_d8a76161ea31c0af

    LOG: Initial PrivatePath = NULL

    LOG: Dynamic Base = NULL

    LOG: Cache Base = NULL

    LOG: AppName = NULL

    Calling assembly : (Unknown).

    ===

    LOG: This bind starts in default load context.

    LOG: Using application configuration file: C:Documents and SettingsAdministratorLocal SettingsApps2.0OO8V8EL.56W1LDVV5JJ.18Xstre..vsto_6da480650dab2fc3_0001.0000_d8a76161ea31c0afStreamingEdge.ExcelPlatformAdapter.dll.config

    LOG: Using machine configuration file from C:WINDOWSMicrosoft.NETFrameworkv2.0.50727configmachine.config.

    LOG: Policy not being applied to reference at this time (private, custom, partial, or location-based assembly bind).

    LOG: Attempting download of new URL file:///C:/Documents and Settings/Administrator/Local Settings/Apps/2.0/0OO8V8EL.56W/1LDVV5JJ.18X/stre..vsto_6da480650dab2fc3_0001.0000_d8a76161ea31c0af/StreamingEdge.ExcelPlatformAdapter.DLL.

    LOG: Assembly download was successful. Attempting setup of file: C:Documents and SettingsAdministratorLocal SettingsApps2.0OO8V8EL.56W1LDVV5JJ.18Xstre..vsto_6da480650dab2fc3_0001.0000_d8a76161ea31c0afStreamingEdge.ExcelPlatformAdapter.dll

    LOG: Entering download cache setup phase.

    LOG: Assembly Name is: StreamingEdge.ExcelPlatformAdapter, Version=1.2.0.0, Culture=neutral, PublicKeyToken=38c26d76b1ac58de

    LOG: A partially-specified assembly bind succeeded from the application directory. Need to re-apply policy.

    LOG: Using application configuration file: C:Documents and SettingsAdministratorLocal SettingsApps2.0OO8V8EL.56W1LDVV5JJ.18Xstre..vsto_6da480650dab2fc3_0001.0000_d8a76161ea31c0afStreamingEdge.ExcelPlatformAdapter.dll.config

    LOG: Using machine configuration file from C:WINDOWSMicrosoft.NETFrameworkv2.0.50727configmachine.config.

    LOG: Post-policy reference: StreamingEdge.ExcelPlatformAdapter, Version=1.2.0.0, Culture=neutral, PublicKeyToken=38c26d76b1ac58de

    LOG: Binding succeeds. Returns assembly from C:Documents and SettingsAdministratorLocal SettingsApplication Dataassemblydl3BM8A5766.TN9N8CKTW6W.M2Jca9b01d21266d8d0_300aca01StreamingEdge.ExcelPlatformAdapter.dll.

    LOG: Assembly is loaded in default load context.

  7. praveenb says:

    Hi Graham,

    It appears like the assembly was loaded correctly. Looking at the location from where the assembly is being loaded (stre..vsto_6da480650dab2fc3_0001.0000_d8a76161ea31c0af) it appears that you are using a VSTO Add-In and NOT a Shared Add-In (or COM Add-In). This explains why the VBS script to do a CreateObject failed as VSTO add-ins are not COM components.

    Since this is a VSTO add-in, please add an environment variable "VSTO_SUPPRESSDISPLAYALERTS" and set its value to "0" to see what is the error that is being thrown.

    To know more about this VSTO_SUPPRESSDISPLAYALERTS see:

    http://msdn.microsoft.com/en-us/library/ms269003(VS.80).aspx

    HTH,

    Praveen

  8. Pallavan says:

    Hi,

    I have doubt on following.

    “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.”

    So if I create shared add-in it will list as mscoree.dll. It is possible to change the name.

    Thanks

    Pallavan

  9. praveenb says:

    Hi Pallavan,

    You have to use a COM Shim for that.

    Please see:

    http://msdn.microsoft.com/en-us/library/bb508939.aspx

    HTH,

    Praveen.

  10. Pallavan says:

    Hi,

    This is pallavan again. I have created shared add-in for Outlook in vb.net. I installed the msi file on another machine. After install it is listed under disabled items(unloaded) in trust center. I have checked everything but no luck not to enable it.

    I am missing anything. Kindly help me on this

    Thanks & Regards

    Gokul

  11. praveenb says:

    Hi Pallavan,

    Anytime an add-in causes Office to do an unsafe exit/crash, it will be disabled. Add try/catch blocks to the onConnection event handler to see if you are hitting any exception there. Also, please use Assembly Binding Log Viewer (Fuslogvw.exe)

    http://msdn2.microsoft.com/en-us/library/e74a18c4(VS.80).aspx

    to see if you are missing any references.

    HTH,

    Praveen.

  12. somu says:

    hello Praveen,

    I am getting error with my anti virus COM add-in "Outlook experienced a serious problem with the 'sunbelt software outlook antivirus object' add-in. If you have seen this message multiple times, you should disable this add-in and check to see if an update is available. Do you want to disable this add-in?"

    I am trying to  find out the fix but I couldn't .  I been seeing the load behavior 3 for this plugin.

    Is there a way to suppress the above message box?

    please help to  fix this bug. This bug is random behavior in nature .

    thanks

    Somu

  13. praveenb says:

    Hi Somu,

    You are seeing the error because Outlook did an unsafe exit while executing one of the call backs in your add-in.

    Place all the code in the Add-in's methods (OnConnect, onDisconnect etc..) inside try/catch blocks and log the exception to troubleshoot further as to what is going wrong.

    There is no way to suppress the dialog apart from making registry changes that are kept to track Outlook crash (not recommended).

    I would suggest first approach to see what's going wrong in your add-in rather than go through this hacky approach.

    HTH,

    Praveen

  14. shiv says:

    I created shared Add in .It is running in my machine proprly.But when I am running same add in set up in other machine then  It is showing plug-in name in Inactive block.

    e.g

    like

    It is comming in inactive block

    myaddin                                      mscoree.dll                          com addin

    And when I try to active then It show Run time exception Load Error.And registry val change from 3 to 2.

    Give me solution for that It is urgent

    I will be thankfull to you.

  15. praveenb says:

    Hi Shiv,

    Did you try the steps mentioned in the blog post? Like, do you see mscoree in disabled items list, did you add try/catch block against add-in callbacks to make sure no exception is being hit, missing dependencies etc…

    – Praveen.

  16. shiv says:

    I tried to generate log by follow these steps

    a)      Open regedit and browse to “HKEY_LOCAL_MACHINESOFTWAREMicrosoftFusion”

    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”

    But logs are  not generating………

    I followed steps  in such a way

    1)- change in registry Load Behavior from 2 to 3

    2)- create DWORD folder inside fusion

    3)-open office ,It was showing add in inactive block ,as I clicked on check box and OK button.It showed Load error,Run time error

    And when I checked Fusion folder in C directory ,I did not get any log file there.

  17. praveenb says:

    Shiv,

    Do you have the correct version of (the one developed for) .NET framework on the target machine?

    What happens if you create a simple VBS (VB Script) file with just a CreateObject line and run the VBS file:

    ——————-

    set o = CreateObject(“ProgId”)

    ——————-

    Does that work? If it doesn't, does that generate any entries in the "C:Fusion" directory?

    -Praveen

  18. Jonas says:

    You the man, fusion did it! Found the missing dll. Packaged it into my setup and now everything is working like a charm!