Troubleshooting and reporting an issue

We care a lot about the quality behind the Rubberduck project and we put in our best efforts to make a high quality software. However, being a open source project maintained by a bunch of volunteers donating their times make it challenging to cover all possible scenarios, especially across a wide variety of environments. This guide is meant to provide a handy reference for those who needs help diagnosing why Rubberduck isn't working on their environment.

Note that all operations described here can be done graphically in a working Rubberduck instance. The steps are only necessary in the situation where Rubberduck is not running or can't be loaded.

Rubberduck doesn't start

You get an error message similar to this:

This usually indicates a misconfiguration with the registry or the installation location. The simplest way to fix this is to uninstall Rubberduck, then install a new version of Rubberduck. Note that if you see multiple instances of Rubberduck listed in the Add / Remove Programs menu, it is recommended that you uninstall them all. There should be only one version at work.

Splash screen nor menu does not show up at all:

We need to ensure that Rubberduck is in fact set up to be loaded automatically. To check this, go to VBE's Add-In Manager.

Select Rubberduck and ensure that both checkboxes are checked to enable automatic loading:

When you check the checkboxes, the splash screen should load immediately once you dismiss the dialog.

However, if Rubberduck is already marked to load/startup automatically, and you still do not see a splash screen, then the next step is to check if there's any logs generated. You can locate the logs manually by opening up a new Windows Explorer window, enter the %APPDATA%\Rubberduck\Logs in the address bar and navigating there. You should see contents similar to this:

If you have a log file, then you can open it in any text editor and review the contents or upload it to a GitHub issue.

No Log files are present

Typically, Rubberduck will not run with logging enabled. It will have some logging at the first run but will automatically disable the logging if the user do not make any explicit changes to the logging level. If you do not see any log files available, you can manually change the logging level by locating the config file and editing it. Open up a new Windows Explorer window and enter %APPDATA%\Rubberduck. You should see a rubberduck.config file which you can then open in a text editor.

The contents of the file may vary from computer to computer but the format should be consistent. In the case of changing the logging level settings, you should locate those two settings, UserEditedLogLevel and MinimumLogLevel within the GeneralSettings section. Ensure that they are set to true and 0, respectively:

<Configuration>
  ...
  <GeneralSettings>
    ...
    <UserEditedLogLevel>true</UserEditedLogLevel>
    <MinimumLogLevel>0</MinimumLogLevel>
    ...
  </GeneralSettings>
  ...
</Configuration>

Note: You can choose to use a higher number for lower verbosity of the logs. 0 will provide the most details, and the higher you go, the less detailed the log becomes.

Save the changes and then try to load Rubberduck.

VBE & Rubberduck crashes with an error, no logs are generated even though logging is enabled

If you find that loading Rubberduck results in a crash, one thing you can try to do is to temporarily rename the rubberduck.config file located in %APPDATA%\Rubberduck. If there's a problem with the configuration, renaming the rubberduck.config will usually fix the crashing because Rubberduck will find that the rubberduck.config file is missing and create a new vanilla file. You can then compare the differences and update the changes one by one until you find the line in the rubberduck.config that causes the crash.

VBE & Rubberduck crashes, no config file exists

Note that if the rubberduck.config file is missing, this is normal since the rubberduck.config file is only created if the configuration is customized in some way. However, you can do some additional troubleshooting by creating the file manually. Here is a minimal working example you can use to get Rubberduck to load. Note this does not include additional sections; only the GeneralSettings which are required for Rubberduck to function.

<?xml version="1.0" encoding="utf-8"?>
<Configuration>
  <GeneralSettings>
    <Language Code="en-US" />
    <CanShowSplash>true</CanShowSplash>
    <CanCheckVersion>true</CanCheckVersion>
    <CompileBeforeParse>true</CompileBeforeParse>
    <IsSmartIndenterPrompted>false</IsSmartIndenterPrompted>
    <IsAutoSaveEnabled>false</IsAutoSaveEnabled>
    <AutoSavePeriod>10</AutoSavePeriod>
    <UserEditedLogLevel>false</UserEditedLogLevel>
    <MinimumLogLevel>6</MinimumLogLevel>
    <EnableExperimentalFeatures />
  </GeneralSettings>
</Configuration>