Excel addins troubleshooting guide

Introduction

So you have deployed your awesome Excel addin in production and all is working fine for some weeks: you are enjoying your success ... But one day the phone rings and the guy at the other side is not really happy; no, he is completely upset and you could almost smell his breath when he screams. But why? Because your awesome addin has stopped working on his workstation without notice.

Sometimes the root-cause is obvious: you have delivered a new version, but in many cases you will hardly ever know the root-cause of this annoying situation: Windows update, Office update, quick and dirty moving/installation of the addin from a workstation to another one, bad alignment of Uranus and Jupiter… 

A wealth of errors can happen, then it’s hard to have them all in mind, especially when you are in a hurry and with stress you start to get mixed up. So to be as efficient as possible you’d better have a checklist and this is precisely what this article will be, enumerating all the errors I have encountered describing usual causes and solutions. 

So let’s troubleshoot! 

0) The magic solution that works almost 50% of the time

If the error message does not inspire you and you want or need to move fast, you can try this as a first shot:

1. Go into the VBA editor (ALT-F11 is a handy shortcut).
2. In the top menu, choose "Tools" then "References":
   

   VBA Tools References

   You should see this popup:

   

   The reference can point to an XLA file or a TLB file (which is the interface of your addin used by VBA).

3. Locate your addin reference (if selected it should be at the top), uncheck it and click "OK".
4. Reopen this popup, locate your addin (you can type its first letter to directly go to the first addin whose name starts with this letter) but this time recheck it.
5. Restart the operation that was broken and cross your fingers, it may be OK now.
6. Still sucks? Follow the rest of this guide depending on your error.

I’ve seen the unreference/re-reference trick working for:

• Error 430 "class does not support automation or does not support expected interface" :
  

  VBA Error 430

  which is typically the consequence of an update of your add-in API like changing the signature of a method.

• "Out of memory" errors:
  

  VBA Out of memory error

• And a bunch of other situations…

If your Excel application is made of normal spreadsheets (XLS, XLSM…) and XLAs, do not forget to update the references for all the files referencing your addin, not just the spreadsheets.

1) Excel is crashing before you can try the magic solution

Sometimes you’re really not in luck and while you feel that a simple "unreference/rereference" could do the job Excel does not give you the opportunity to try it as it crashes before you can access the VBA editor.

This issue can occur if the workbook is referencing the absolute path to the TLB on your development environment and you deploy the workbook as is in your production environment where the TLB will probably be in another place (typically a sub-directory of "Program Files"). It can also occurs if you have multiple versions of your addin on the workstation. It can often happens on your development workstation if:

• you develop with multiple workspaces (one for each of your SVN/Git branches) and there is a mix between the different TLBs and addins : you can try a full cleanup (including Windows registry) and rebuild from the workspace you’re currently working on
• you use a task manager or integration server like Jenkins (ex Hudson) which builds your addin and register it into the system in your back : you can temporarily disable the task that breaks your setup

If the workbook is broken in production, you can use two solutions :

1. Start Excel in safe-mode, either by starting it from the "Run" popup (shortcut is Windows-R) with the "/safemode" option :
   

   Run Excel in safe-mode

   or by pressing continuously the CTRL key while starting it which should trigger the following popup :

   

   Excel start safemode.

   Once Excel is started in safe-mode load the broken workbook. You should be able to access the "References" popup and do the unreference/rereference trick.

2. You can temporarily move or rename the TLB file and starts your Excel application as usual. Excel should not crash anymore and starts as usual, only complaining about the missing TLB. You can now move/rename the TLB as it was before, proceed to the "unreference/rereference" trick and then save the workbook to ensure the correct reference is kept. All should be fine at the next startup.

2) "Error in loading DLL" when referencing a TLB

If, when referencing a TLB, you see this popup :

VBA Error in loading DLL

this is probably the sign that Excel cannot access the TLB file, the root cause can be :

• a simple installation issue : the TLB not being where it is expected (you can check the expected path in the Windows registry using RegEdit); so check the correct installation of your application and reinstall it if necessary.
• a user rights issue with the TLB, and more generally all the installation items : this can happen if you have installed your application with a user that is not the one currently trying to use the application (e.g. a remote user). You can then either:
  • proceed to a dedicated reinstallation for the current user,
  • change the rights of the installation items to allow him full access,
  • or add him to a user-group that has the required rights,

  whichever you find easier and cleaner in your situation.

3) "Error in loading DLL" when compiling the VBA project

If this error occurs when the VBA code is compiled, either automatically when accessing a function/sub that uses the addin API or manually when clicking the Debug/Compile menu item then check if you have recently changed the settings of a dependency (e.g. of your .Net (C#, VB.Net…) project) that contains COM types you expose through your addin API.

I’ve seen this issue once in a C# project with the ADODB dll when the "Embed Interop Types" option was set to "True" in the reference properties. With only this settings and "Copy Local" to "False" a method of the addin that returned an ADODB connection was broken in Excel 2003 on Windows XP whereas all was working fine on Excel 2010 on Windows 7. I’ve not dived into the details but it seems the "Embed Interop Types" feature is not retro-compatible or may need some additional setup on the workstation, which in both case made it unusable.

So, setting "Embed Interop Types" to "False" and reverting "Copy Local" to "True" solved the issue caused by Visual Studio 2010 because it activates these settings by default with .NET 4.0 projects (the project had recently been migrated from .Net 3.5 to .Net 4.0)!

ADOBD Reference Properties

As often VS wanted to help but broke something " class="wp-smiley" />

4) The addin does not want to load

If you can see your addin in the "COM Addins" list and you can check it :

COM addin checked

but when you reopen the "COM Addins" popup your addin is not checked anymore, it’s the sign Excel cannot or does not want to load the addin.

If your addin throws an exception when loaded, ie in the "OnConnection" method, you should see a warning at the bottom of your addin description, in the "Load Behavior" field :

Excel COM addin error

You can reproduce this behavior with a simple code :

public void OnConnection(object application, Extensibility.ext_ConnectMode connectMode, object addInInst, ref System.Array custom)
{
    applicationObject = application;
    addInInstance = addInInst;

    throw new Exception("Boom!");
}

But if your addin causes more serious damages like an Excel crash, what you can experiment with such a code :

public void OnConnection(object application, Extensibility.ext_ConnectMode connectMode, object addInInst, ref System.Array custom)
{
    applicationObject = application;
    addInInstance = addInInst;

    System.Diagnostics.Process.GetCurrentProcess().Kill();
}

then Excel won’t trust it anymore and may put in quarantine ALL the addins loaded at the time of the crash! If you are lucky you should see this message at the next startup of Excel :

Excel addin serious problem

You can choose to give your addin a second chance by answering "No" or you can answer "Yes" so the addin will stay disabled and you won’t be able to load it into Excel until you notify Excel the addin should not be kept in quarantine any longer.

But if you are in doubt and think your addin may have been disabled how to check ? You have at least two solutions :

•  using Excel 2010 : go to the "File" ribbon tab then "Options" :
  

  Excel2010 File Options

  You should see the "Excel Options" popup in which you now select "Add-Ins" :

  

  Excel 2010 Options Add-Ins

  From here scroll down to the bottom of the list where the disabled items are listed. Here is an example of a too zealous Excel that has disabled all the COM addins (and they were a lot!) :

  

  Excel2010 Disabled addins

  To show the culprit of all this mess use the "Manage" drop-down at the bottom of the window and choose "Disabled Items" :

  

  Excel 2010 Go To Disabled

  then click the "Go…" button to show the bad guy :

  

  Excel 2010 Culprit Addin

  If you forgive your addin then select it and click "Enable" then "Close" :

  

  Excel 2010 Addin Reenable

  You should now be able to reload it and all the other addins disabled due to the crash via the "COM Add-Ins" popup.

• using the Windows registry : Excel stores the disabled items list into the registry under the keys "…\Software\Microsoft\Office\14.0\Excel\Resiliency\DisabledItems", e.g. "HKEY_CURRENT_USER\Software\Microsoft\Office\14.0\Excel\Resiliency\DisabledItems". If an addin has been disabled you’ll find a binary key holding its name :
  

  RegEdit DisabledItems Key

  We can read the identity of our explosive addin : "boomaddin". If you want to reenable it you can either:

  • delete the numerical entry (here "5793E01E")
  • delete the whole "DisabledItems" key

  Note that this change will be effective only for the next Excel instances, so you’ll have to restart your application to be able to load your addin as usual.

5) NullReferenceException thrown by the .Net (C#, VB.Net…) addin code

"Object not set to an instance of an object" like errors generally happen when your .Net addin has not been loaded by Excel, so initialization code has not been executed (typically the part that captures the Excel application instance loading the addin). Therefore your addin code may be naively accessing not initialized references.

Indeed you’ll typically use code like this one :

public void OnConnection(object application, Extensibility.ext_ConnectMode connectMode, object addInInst, ref System.Array custom)
{
    // keep the application object for future use
    applicationObject = application;
    addInInstance = addInInst;

    // other initialization code
}

public void DoSomething()
{
    // oops! if the addin is not loaded this code will throw a NullReferenceException
    (applicationObject as Application).ActiveCell.Value2 = "Something";
}

If the addin is not loaded the "OnConnection" method will not be called, then the "applicationObject" reference will not be initialized with the running Excel instance.

It could also happen that something is broken inside the "OnConnection" method itself preventing it from running to its end, letting the addin half-initialized (which is far more dangerous than not initialized at all as the resulting errors and behavior will be more surprising and entertaining ). So you should always keep track of your addin state and notify of any inconsistency : using a simple boolean flag set to "true" at the end of initialization (typically at the end of the "OnConnection" method) should be sufficient in most cases.

So refer to point 4) to check the status of your addin.

6) Generic run-time error

Sometimes you get this kind of anonymous error popup :

Excel Automation error

To make sense of this cryptic and apparently useless message you should lookup your error-code/HRESULT (here 80131524) in this list.

In this case the error was COR_E_DLLNOTFOUND due to a missing native DLL used through DllImport by the C# addin (itself called by a VBA macro).

Deployment of native DLLs often causes issues that you can troubleshoot using Dependency Walker (see my article about it).

7) All other unknown mystic errors

If you have any error not referenced here, for which you don’t find a solution by googling it and whose root-cause is impenetrable then, in desperation, you can try to remove any trace of your addin in your system : 

• remove all the files and directories that contain the assets of your application like XLS/XLSX/XLSM spreadsheets (whose references could have been corrupted), DLLs and TLBs…
• cleanup the registry by hand by looking for all the references to your addin : DLLs and TLBs keys should be enough but you can also remove all the COM registration information of your types.

Then reinstall the addin and cross your fingers…

It should be relatively uncommon to need this : in the last year I’ve never had to go this far thanks to my better understanding of Excel addins and this kind of checklist.

Conclusion 

If this article has helped you troubleshoot an issue I’d like to read your story.

If you have any remarks or suggestions about this article or if you know other errors with their standard fixes please share by letting a comment, I’ll do my best to update this article with your feedback.