Debugging guide for common Chime setup issues.

README | Configuration | Architecture | Integrations | Testing

Validate Configuration

Start with:

M-x chime-validate-configuration

Interactive validation prints a checklist in *Messages* showing whether org-agenda-files is set, whether files exist, whether org-agenda is loadable, and whether modeline support is available.

Enable Debug Mode

Enable debug mode before loading chime:

(setq chime-debug t)
(require 'chime)

This loads chime-debug.el and provides:

M-x chime-debug-dump-events — show stored upcoming events
M-x chime-debug-dump-tooltip — show tooltip content
M-x chime-debug-config — dump complete configuration
M-x chime-debug-show-async-stats — show async success/failure stats
M-x chime-debug-force-check — force an immediate diagnostic check

Debug mode also logs event loading and async process timing to *Messages*.

No Notifications Appearing

Check these in order:

Verify a notification daemon is running on your system.
- Linux examples: dunst, mako, swaync
- macOS and Windows have built-in notification support.
Verify chime-mode is enabled:
```
M-: chime-mode
```
Check alert.el style configuration:
```
(setq alert-default-style 'libnotify)
```
Run M-x chime-check manually.
Check *Messages* for errors.
Enable debug mode for more detail.

No Sound Playing

Verify a sound file is configured:
```
M-: chime-sound-file
```
Check that the file exists:
```
M-: (file-exists-p chime-sound-file)
```
Test sound directly:
```
M-: (play-sound-file chime-sound-file)
```
Ensure your system has audio support configured.

Set chime-sound-file to nil to disable sound.

Events Not Being Detected

Common causes:

The org file is not in org-agenda-files.
The timestamp is all-day and you expected it in the modeline. All-day events do not appear in the modeline.
The timestamp is a diary sexp such as <%%(...)>. Chime does not support those as event timestamps.
Filters are excluding the event.
The event is outside the modeline or tooltip lookahead window.

Chime supports timed 24-hour and 12-hour timestamps:

* 24-hour event
<2026-05-10 Sun 14:00>

* 12-hour event
<2026-05-10 Sun 2:00pm>

Modeline Is Empty

Check:

chime-enable-modeline is non-nil.
chime-modeline-lookahead-minutes is greater than zero.
There is a timed event inside the modeline lookahead.
Events are visible to org-agenda-files.

All-day events may appear in the tooltip, but never in the modeline itself.

Relevant settings:

(setq chime-tooltip-lookahead-hours 168)
(setq chime-modeline-tooltip-max-events 5)
(setq chime-tooltip-show-all-day-events t)

If you increase chime-tooltip-lookahead-hours a lot, async checks can take longer because chime fetches a wider agenda span.

Multiple Emacs Instances Produce Duplicate Notifications

If you receive duplicate notifications for every event, you likely have multiple Emacs processes running with chime-mode enabled.

Check running Emacs processes:

ps aux | grep emacs

Common scenario:

emacs --daemon
emacsclient -c
emacs &

The final command starts a second standalone Emacs process, so chime runs twice.

Choose one approach:

Use daemon + emacsclient consistently.
Use standalone Emacs processes only.

To stop a daemon:

emacsclient -e "(kill-emacs)"

Startup Validation Fails Before org-agenda-files Loads

If your configuration populates org-agenda-files asynchronously, chime may validate before those files are ready.

Options:

;; Give startup more time before first check.
(setq chime-startup-delay 20)

or ensure org-agenda-files is set before enabling chime-mode.

Async Check Failures

Chime warns after repeated async failures. Tune or disable those warnings:

;; Default
(setq chime-max-consecutive-failures 5)

;; Disable warnings
(setq chime-max-consecutive-failures 0)

For custom predicate functions, ensure any variables they depend on are available in the async subprocess:

(setq chime-additional-environment-regexes '("my-custom-var"))

Modeline Frozen on a Stale Countdown

If the modeline shows a countdown that never advances past an old event, the background fetch process likely hung, blocking every later check. Chime's watchdog interrupts a fetch after chime-async-timeout seconds (default 120) and logs "Async watchdog" to *Messages*, so a hang heals itself within one timeout plus one check interval.

If you see repeated "Async watchdog" log lines, something in the fetch is consistently hanging or too slow:

A very large agenda can legitimately exceed the timeout — raise it: (setq chime-async-timeout 300)
An entry in org-agenda-files pointing at a deleted file used to hang the fetch on org's recovery prompt; chime now skips missing files, but cleaning up stale entries keeps the agenda scan honest.