Troubleshooting and Bug Reporting

Deciding what level the problem lives at

If you are experiencing a crash or very slow performance with a particular query, please try it on the command line using "notmuch search" or "notmuch show"; it's easier for us to debug if the problem is there, and it's useful to know if the problem is introduced by a front end.

Understanding the structure of a problematic message

The script print-mime-structure prints out the mime structure of an email message as a (text) tree. This is usually safe to share and can help people understand your problem.

Troubleshooting the Emacs interface

It's very easy for Emacs packages to interfere with each other. For this reason we ask you to try and find the problem with only notmuch loaded. You can do this with

emacs -Q -L /path/to/your/notmuch/lisp --eval "(require 'notmuch)"

where /path/to/your/notmuch/lisp is either to the emacs directory in the source, or the installed (and possibly compiled) version installed by your package manager, e.g. /usr/share/emacs/site-lisp/notmuch. After Emacs starts, run the command that is giving you trouble using e.g.

M-x notmuch

or

M-x notmuch-mua-mail

Bug and patch tracking

Bug reports should be sent to the Notmuch mailing list notmuch@notmuchmail.org.

Bugs are tracked using a collaborative tagging tool call nmbug. If you submit lots of bugs and/or patches, you may want become involved with this tagging process, but feel free to just send mail to the list; someone will tag messages appropriately. The status of bugs and current patches can also be followed online.

Debugging Queries

If a search doesn't seem to do what you want, you can enable query debugging to print the Xapian queries the Notmuch library constructs by setting the NOTMUCH_DEBUG_QUERY environment variable to a non-empty value.

For example:

    $ NOTMUCH_DEBUG_QUERY=1 notmuch search big brown fox
    Query string is:
    big brown fox
    Exclude query is:
    Xapian::Query()
    Final query is:
    Xapian::Query((Tmail AND Zbig:(pos=1) AND Zbrown:(pos=2) AND Zfox:(pos=3)))

Rescuing your tags.

If you're database is corrupt and you don't have a backup, a modified version of xapian-check might still save your tags.