Beginner’s Guide to Troubleshooting Emacs Problems – an Org-roam Edition
Intro
Emacs is infinitely enhanceable. You can pick features and functions you like from the ever-growing universe of Emacs packages and hacks. You can also whip up some Elisp code to mould your Emacs in the way you like. Great!
On the flip side, this degree of freedom often bites you when you have errors and issues with your Emacs. Is the error caused by my hack I did yesterday? Or is it really because of the new package I installed this morning?
Below is a quick guide on how to troubleshoot Emacs problems. There are good guides already available for Emacs in general (e.g. this one). What I am trying to do here is to adjust this guide for beginner Org-roam users, in the hope to help them analyse issues specific to Org-roam more systematically.
I will focus on how to isolate an issue so that you can be sure that the error you are looking at can be attributed to some part of Org-roam (or not).
If you can isolate your issue and report the way you can reproduce it step-by-step, you will greatly help the Org-roam project fix it. Even better, you may be able to fix it yourself, if you can confidently see it is coming from a specific part of your configuration.
Steps
I use Org-roam and Emacs on Windows 10. The steps I describe here, though, should be applicable to macOS and Linux.
1. Back up your .emacs.d
Rename your .emacs.d folder to keep it as a backup. After your analysis, you want to come back to where you started.
I tend to use Explorer and rename ~/.emacs.d to something like ~/emacs.d (dropping the .).
2. Back up your org-roam-directory
By default, your org-roam-directory is ~/org-roam. If you have changed it, then the following steps should not affect your Org-roam notes and db. If you have kept the default, you might want to also change the directory name to keep it as a backup.
If you suspect the issue in question is related to your particular notes, and use them as part of analysis, then I would suggest to create a copy of the entire folder as a backup.
3. Start Emacs with the -Q option.
The easiest for Windows users would be to open Windows menu, and directly type emacs -Q, like this in the image.
If you are in cmd or Power Shell, you can type emacs -Q (for macOS users, Terminal; for Linux users, I assume you know what I mean).
You should see Emacs launch into a *scratch* buffer, like this:
Note it’s a capital “Q”. Using -q would result in the start screen of Emacs.
This is what people refer to as “vanilla” Emacs. No configuration applied; the clean slate you want to start with.
4. Install org-roam
Now let’s add org-roam and only the packages it needs as prerequisites.
You can keep the two lines in the buffer, or remove them. They don’t do anything; they are comments
;; This buffer is for text that is not saved, and for Lisp evaluation.
;; To create a file, visit it with C-x C-f and enter text in its buffer.
If you keep them, under them, type the following (copy and paste should do).
(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)
Source: GitHub - melpa/melpa: Recipes and build machinery for the biggest Emacs package repo
Evaluate this whole buffer with M-x eval-buffer.
After this, manually call the following two commands.
M-x package-refresh-contents RET
M-x package-install RET org-roam RET`
If your computer is connected with the internet, you should see your Emacs download bunch of packages and compile them.
Now you should be able to start using org-roam on top of your vanilla Emacs. It’s the minimal state to use org-roam.
5. (Optional) Configure key bindings
Optionally, you can set Org-roam key bindings in the scratch buffer.
Type the following under (package-initialize):
(global-set-key (kbd "C-c n r") #'org-roam-buffer-toggle-display)
(global-set-key (kbd "C-c n i") #'org-roam-insert)
(global-set-key (kbd "C-c n /") #'org-roam-find-file)
Invoke the command M-x eval-buffer to evaluate the entire buffer. Don’t worry about the previous lines from (require 'package) – they get evaluated, too, but they should not do any harm for our analysis.
6. Analysis
On this clean slate, try to reproduce the issue you want to analyse. This way, if you see it again, you can be sure that it is caused by somewhere within Org-roam and its prerequisites (and off chance, in the small amount of configuration you have done in the scratch buffer). If you don’t see it, then you can be sure it’s not caused by Org-Roam; you need to look elsewhere.
If you can reproduce the problem, record the steps. This is the step-by-step guide to reproduce the problem that you can report to the Org-roam project.
Another useful piece of information you can generate is a “backtrace”. It’s an Emacs generated trace of programs up to the point of error. To get it, invoke M-x toggle-debug-on-error, and then reproduce the error. You should see *Backtrace* buffer pop up, like this:
There are more ways to analyse issues further such as edebug. But that is beyond the scope of this guide.
7. Go back to where you started
After the analysis, clean up and go back to where you started. Quit Emacs. Your vanilla Emacs would have automatically created new folders named .emacs.d and org-roam (for org-roam, it can be your original, not a new one, of course).
Inside .emacs.d folder (from Step 1), you should see sub-folders such as elpa where you see org-roam and other packages you installed. You can safely delete this temporary .emacs.d folder. Bring back your original .emacs.d by renaming it back.
For the org-roam folder (from Step 2), too, you can delete it and bring back the original. If your normal org-roam-directory is org-roam and you have kept your original for analysis, keep it; the vanilla Emacs does not overwrite it.
Launch your Emacs to ensure that it is as it was before the analysis. The problem you analysed is still here, but now you know if it is caused by something inside Org-roam or outside it.
Coda
That’s it for now, folks.
Thanks for reading. Please advise if there are misunderstanding and/or significant omission on my part. All feedback welcome.
Hope some of you find it useful 