Guide to Venkman for debugging Firefox addons



Since ChromeBug for Firefox seems no longer maintained, Venkman remains the only alternative for debugging Firefox addons (Firebug won't work for addons).

Using Venkman has many gotchas, I try to document them here to make the debugger more-or-less usable. I've been able to debug addons on Firefox 15 that call NPAPI plugin generated with FireBreath this way.

Still, Venkman is pain at times (it is buggy itself).

This text was generated by doxygen, I've put the source here:

Install Venkman

It is suggested that you use a clean profile for debugging your extension using:

firefox -no-remote -P new-profile-name

First time the above command is run, you'll get the profile manager popup. Once you create the named profile "new-profile-name", it will use that named profile.

Install Venkman from

Install your addon into Firefox and restart.

Using Venkman - magic setup to make breakpoints work

Open Venkman from menu Tools-JavaScript Debugger. Two most important tricks for breakpoints to work:

1. You must disable "Exclude Application Files"

First of all, in Venkman's menu uncheck from menu Debug-Exclude Application Files:


2. You must set an evaluation object, best to use "browser.xul"

Look for the tab/window "Open windows". By default it's a tab next to "Loaded Scripts":


You'll use it often, let's put it to a better accessible place:

"Open Windows" dockwindow with a treeview should appear at bottom left:


The treeview root should read "browser.xul" and not "Browser Window" - make sure you unchecked that "Exclude application files" before.

Right-click "browser.xul" and check "Set as evaluation object" from context menu:

At some undefined times (e.g. after breakpoint is hit), evaluation likes to "uncheck" itself, see if still checked when breakpoints are not working. (Even better, make sure that evaluation object is set at the time you set the breakpoint.)
Using a tab as evaluation object may work, but don't really count on that

3. Set the breakpoint

If you don't see your xul/js file in the "Loaded Scripts" dockwindow, switch to Firefox browser window (don't close Venkman window). Open a tab with some page that will trigger your script somehow. Now your source file hopefully appear in Venkman.

Expand the tree under your source file or double-click to see it in "Source code" window. Scroll to desired line, put a breakpoint there by clicking the column left to line number (or from context menu by right-clicking the line).

Go to Firefox browser and do an action that should trigger the line where you put the breakpoint.

  • Bug: after setting the breakpoint, you might not see 'B' or 'F' next to line number, but it's visible in Breakpoints window. Scroll the line with breakpoint out of "Source Code" view, and scroll it back. It should be visible now.
  • Sometimes you may see all methods of your objects in the treeview under the source file in "Loaded Scripts", sometimes you won't. It may flip vice versa (no idea when).
  • Difference between 'B' and 'F' (breakpoint and future breakpoint) is described in Venkman FAQ, but I feel it does not correspond 100% to actual state. When in doubt, put a breakpoint on one line and future breakpoint on the next line.

Hackish way to set a breakpoint

If "normal" way of setting breakpoint does not work, here is a hackish workaround. It's a method of last resort, really.


Venkman windows disappeared

This is a very annoying bug. Happens for me on one installation after every start of Firefox (not restart), other installation is OK. It looks like this:


Option 1


Option 2


Source file not visible in Venkman's Loaded Scripts



License for this text: WTFPL (do whatever the fuck you want public license)

Generated on 26 Sep 2012 for GuidetoVenkmanfordebuggingFirefoxaddons by  doxygen 1.6.1