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!
If the error message does not inspire you and you want or need to move fast, you can try this as a first shot:
- Go into the VBA editor (ALT-F11 is a handy shortcut).
- 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).
- Locate your addin reference (if selected it should be at the top), uncheck it and click "OK".
- 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.
- Restart the operation that was broken and cross your fingers, it may be OK now.
- Still sucks? Follow the rest of this guide depending on your error.
I’ve seen the unreference/re-reference trick working for:
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 :
- 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.
- 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 :
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)
{
applicationObject = application;
addInInstance = addInInst;
}
public void DoSomething()
{
(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.