Most Org problems are not Org bugs; they are configuration folklore, version mixing, or a package interacting with another package.
When something breaks, resist editing configuration at random. A disciplined sequence isolates the cause faster than any single clever fix.
The procedure
- Read the exact error and the
*Messages*buffer. - Enable M-x toggle-debug-on-error and reproduce to get a backtrace.
- Describe the command, variable, key, and mode with C-h f, C-h v, C-h k, and C-h m.
- Check versions with M-x emacs-version and M-x org-version.
- Reproduce under
emacs -Q; load only Org and a minimal snippet. - Add external packages back one at a time.
- Search the current official manuals and release notes using the exact symbol.
An error that disappears under emacs -Q is probably configuration or extension interaction. An error still reproducible with bundled Org and a tiny file is a stronger Org bug candidate. When you report, include exact versions, minimal source, steps, and the backtrace.
Symptom-to-checks table
| Symptom | Checks |
|---|---|
| File absent from Agenda | Inspect org-agenda-files; save file; confirm active timestamp or TODO; refresh with r |
| Capture template error | Check tuple shape, target path, parentheses, % expansion, and *Messages* |
| Refile target missing | Save target file; inspect org-refile-targets; check maximum level and completion path |
| Babel language disabled | Inspect org-babel-load-languages; require the correct ob-*; verify the external interpreter |
| Block fails | Run the code outside Org; inspect working directory, session, header arguments, and backtrace |
| Export fails | Isolate the smallest document; inspect the exporter backend and external TeX or Pandoc logs |
| Link breaks after move | Prefer IDs for durable targets; refresh ID locations; avoid unmanaged attachment moves |
| Bundled/external conflict | Inspect org-version, locate-library, and load path; use one install method |
| Slow Agenda | Reduce scope, exclude archives, disable suspect hooks, profile |
Controlled experiments
Good debugging changes one variable at a time. Org problems often cross four layers: Org syntax, Emacs configuration, an external package, and an operating-system program. A minimal reproduction file keeps those layers separate:
* TODO Minimal task
SCHEDULED: <2026-09-02 Wed>#+begin_src python :results output
print("test")
#+end_srcStart emacs -Q, open the file, and reproduce. -Q omits personal and site initialization, yet it still uses bundled Org and still depends on external Python if you test the block. For Lisp faults, M-x check-parens finds an unbalanced parenthesis and M-x locate-library shows which physical org.el will load. For a key that misbehaves, run C-h k in the exact context, then invoke the command by M-x to separate "command broken" from "binding replaced." A useful help request states expected behavior, actual behavior, exact versions, minimal Org text, minimal Lisp, steps, backtrace, and whether emacs -Q changes the result.
Summary. A repeatable procedure beats guesswork: read the exact error, reproduce under `emacs -Q`, and change one variable at a time. A symptom-to-checks table turns the common failures into fast lookups.
Exercises
- Basic: Use `C-h k`, `C-h f`, and `C-h v` to investigate one Org action of your choice, then read the docstring it points to.
- Practical: Intentionally break a capture target (wrong path or mismatched parentheses), reproduce the error, then reduce it to a minimal configuration that still fails.
- Advanced: Profile a slow Agenda view with `M-x profiler-start` (CPU), reproduce it once, and read the report to distinguish parsing cost from time spent in your own hooks.