Org Agenda Hangs When Files use INCLUDE

Site Nav


An issue encountered introduced when using #+INCLUDE directives in this site is that it seems to cause a hang if such files are registered in org-agenda-files. As I'm using this site to coordinate assorted public projects it would preferably be able to hold TODO items which could be displayed in collected agendas, so resolving this issue will be something I'll need to dig in to.

Initial Discovery

Some good first steps in any software project are to see if the issue is already filed somewhere and potentially resolved in a newer or alternative version. Org-mode uses a mailing list and IRC channel for help[emacs-org-mode-community] and the former didn't provide any promising results from a cursory search. My usual MO in these scenarios is to start digging a bit so that I can do some combination of performing a better search, asking a more informed question, and working towards a resolution. The next step is therefore to upgrade my org-mode and specifically switch to a fully updated source checkout rather than a released package. This also frees up to use any fun new org features which aren't available in the version that is packaged with emacs (since I've already incurred the cost of relying on non-builtin packages). At the moment this bumps me all the way up from 9.3 to 9.4!.


org-mode nicely includes the path and command to clone its source repository right on its home page[emacs-org-mode-home] so getting the source is simple (some other projects often require one or two clicks to track down the url which can obviously be exhausting). Even more helpful are the instructions in the Installation node of the Org's info manual [emacs-org-mode-info] which also provides the right installation and activation invocation. The checked out code is wired up in my emacs init file.


Loading the functions from the latest source code appears to have resolved the issue, so there's nothing particularly interesting to cover. I ended up evaluating the buffers within the source checkout to make sure to use those definitions (and chasing down and evaluating buffers as needed to quiet errors). The init file updates should reload the latest source on the next startup.

The specific issue could be tracked down through some combination of examining changelogs and diffing or bisecting the code, but there's no motivation to dig any further into this issue now that it's resolved.

TODO New Case

After resolving the initial issue I once again suffered from the agenda hanging after adding a TODO item to a page on this site. Brief experimentation showed that the agenda hangs when the TODO is attached to a headline at level four but not one at three. The short term remediation is to superficially promote that headline but the underlying issue and specific variations of when it manifests should be given more attention.

Another TODO caused the same issue at level 3 but not at level 2: I'd speculate that the issue is related to surrounding context such that a TODO that has a sibling or parent block may suffer from issues which is avoided if the TODO is elevated from that context.



  • [emacs-org-mode-community] @miscemacs-org-mode-community, title = Org mode for Emacs - Community, url =, notes = This has pointers to community resources which which to engage if more interesting org use or contributions are pursued., status = done,
  • [emacs-org-mode-home] @miscemacs-org-mode-home, title = Org mode for Emacs, url =, notes = Solid overview with links out to some interesting details. Worth mining for additional content; worg should likely be cloned and read and HTML publishing stuff borrowed in addition to other links off of this site., status = done,
  • [emacs-org-mode-info] @miscemacs-org-mode-info, title = The Org Manual (Info), url =, status = wip,

Author: mwhipple

Created: 2020-10-27 Tue 19:36