Hunt down errors in elisp files.
Emacs Lisp
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.gitignore Ignore cask Mar 24, 2015
.travis.yml Fix travis Mar 22, 2015
Cask Fix tests Mar 22, 2015 Version 1.3.1 Jun 24, 2016
bug-hunter-test.el Fix test Jun 15, 2015
bug-hunter.el Version 1.3.1 Jun 24, 2016
cl-example.png Better Readme Mar 25, 2015
hunter-screencast.gif Screencast Jun 15, 2015
hunter.png Write readme Mar 22, 2015

hunter.png The Bug Hunter

Automatically debug and bisect your init (.emacs) file!

The Bug Hunter is an Emacs library that finds the source of an error or unexpected behavior inside an elisp configuration file (typically init.el or .emacs).


Usage Examples

Automated error hunting

If your Emacs init file signals an error during startup, but you don’t know why, simply issue

M-x bug-hunter-init-file RET e

and The Bug Hunter will find it for you. Note that your init.el (or .emacs) must be idempotent for this to work.

Interactive hunt

If Emacs starts up without errors but something is not working as it should, invoke the same command, but choose the interactive option:

M-x bug-hunter-init-file RET i

The Bug Hunter will start a separate Emacs instance several times, and then it will ask you each time whether that instance presented the problem you have. After doing this about 5–12 times, you’ll be given the results.

Assertion hunt

The Bug Hunter can also find your issue based on an assertion. Essentially, if you can write a code snippet that returns non-nil when it detects the issue, just provide this snippet as the assertion and the Bug Hunter will do the rest.

For example, let’s say there’s something in your init file that’s loading the cl library, and you don’t want that. You know you’re not loading it yourself, but how can you figure out which external package is responsible for this outrage?

M-x bug-hunter-init-file RET a (featurep 'cl) RET

That’s it! You’ll be given a nice buffer reporting the results:


  • Are you getting obscure errors when trying to open “.tex” files?
    • Don’t despair! Just use (and (find-file "dummy.tex") nil) as the assertion.
  • Did ox-html stop working due to some arcane misconfiguration?
    • Just write an assertion that does an export and checks the result.
  • Does some random command suddenly bind itself to C-j and you can’t figure out why?
    • (eq (key-binding "\n") 'unwanted-command) is the assertion for you!

Finally, you can also use bug-hunter-file to hunt in other files.


The Bug Hunter is available from GNU Elpa to all Emacs versions since 24.1. To install, just issue

M-x package-install RET bug-hunter and other literate-style configs

Some people (me included) like to organize their init files by writting it in org-mode instead of Emacs-Lisp. This usually involves adding something like this to init.el,

;;; Maybe some code up here ;;;
(require 'org)
(org-babel-tangle-file "~/.emacs.d/"
(load "~/.emacs.d/org-init.el")

At first, this makes the Bug-Hunter essentially useless, for it will do the hunting in init.el instead of the much more extensive org-init.el. The name of the second file (org-init.el) will vary, but the point is the same. But fear not! There’s a simple solution:

  1. If you have any code above the call to org-babel-tangle-file, copy that to the top of org-init.el (or whatever is the name of your tangled file). This includes that (require 'org) over there.
  2. Invoke M-x bug-hunter-file (instead of bug-hunter-init-file). It will ask you which file to debug, and you need to point it to your tangled output file org-init.el.