OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
apps-services low common DISPUTE

Debug a systemd timer that never fires

omarchyarchendeavouroscachyosmanjarosystemdlaptopdesktop
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Checked against man systemd.timer, man systemd.time, man systemctl and man environment.d on this workstation (systemd 261.2-1, omarchy 4.0.2-1), the systemd v261 source, and https://wiki.archlinux.org/title/Systemd/Timers. Nearly all of the record held, and I exercised every command in the fix on this machine. Confirmed here: systemd-analyze calendar "*-*-* 04:00:00" prints Normalized form and Next elapse, --iterations=5 "Mon..Fri 22:30" prints five iterations, calendar weekly normalizes to Mon *-*-* 00:00:00, *-*-* 4:00:00 normalizes to *-*-* 04:00:00, and Mon,Tue *-*-01..04 12:00:00 returns Mon 2026-11-02, Tue 2026-11-03, Tue 2026-12-01 and Mon 2027-01-04, which is exactly the "1st to 4th, but only if Mon or Tue" reading the record gives. A malformed expression errors with Failed to parse calendar specification '*-*-* 25:00:00': Invalid argument and exit 1. The stamp-file location is right and more precise than the Arch wiki, which says ~/.local/share/systemd/: this machine has ~/.local/share/systemd/timers/stamp-omarchy-sync-stignore.timer, zero bytes, mtime matching LastTriggerUSec. WantedBy=timers.target, list-timers --all and enable --now are all confirmed by the wiki and by man systemd.timer. Three corrections. First, the danger is wrong about why WakeSystem=true fails, and this record is about user timers. man systemd.timer (261.2-1) says of WakeSystem=: "Note that this functionality requires privileges and is thus generally only available in the system service manager." Hardware support is the secondary condition, not the primary one. The quoted error string Failed to enter waiting state: Operation not supported is also not what systemd 261 emits: src/core/timer.c at tag v261 logs Failed to add monotonic event source: %m or Failed to add realtime event source: %m and then falls through to timer_enter_dead(t, TIMER_FAILURE_RESOURCES), and TIMER_FAILURE_RESOURCES maps to the string resources, so Failed with result 'resources' is real and the first half of the quote is not. I replaced the invented string rather than guess an errno, and I did not exercise this, because creating or starting a unit was out of scope. Second, the stamp-file step gives an undocumented rm as the method and follows it with restart. man systemd.timer says "Use systemctl clean --what=state ... on the timer unit to remove the timestamp file maintained by this option from disk", and man systemctl adds that "the specified units must be stopped to invoke this operation", which restart does not satisfy in the right order. The fix now gives stop, clean, start, and keeps the hand deletion as the equivalent with the path. Third, the record frames the cause as exactly three traps and the symptom explicitly includes NEXT as -, but this machine has a live counter-example none of the three explain: omarchy-sync-stignore.timer in ~/.config/systemd/user/ is enabled and active with LastTriggerUSec=Sun 2026-09-06 01:50:36 PDT, which predates the current boot at 2026-09-06 02:27:48, and it reports NextElapseUSecMonotonic=infinity with an empty NextElapseUSecRealtime after 5 days of uptime. It uses only OnBootSec=3min and OnUnitActiveSec=1h plus Persistent=true with no OnCalendar=, the service it triggers reports an empty ActiveEnterTimestamp, and man systemd.timer states that Persistent= "only has an effect on timers configured with OnCalendar=" and that the immediate-elapse-if-in-the-past rule applies to OnBootSec= and OnStartupSec= but "is not the case for timers defined in the other directives". I added that as a fourth trap and as a show-based diagnostic, and I deliberately did not assert a mechanism for why this particular timer lost its anchor, because I could not pin it down without creating units. I also made the graphical-session.target line concrete, since it was the one unsourced assertion in the record and it is the part that is Omarchy-specific. Confirmed on this machine: Hyprland runs as the user unit wayland-wm@hyprland.desktop.service, /usr/share/omarchy/default/hypr/autostart.lua imports the session environment once at hyprland.start, systemctl --user show-environment contains WAYLAND_DISPLAY=wayland-1 and OMARCHY_PATH=/usr/share/omarchy during a graphical session, and Omarchy's own shipped units use exactly the After=graphical-session.target plus PartOf= plus ConditionEnvironment=WAYLAND_DISPLAY pattern with absolute /usr/bin/omarchy-* paths (/usr/share/omarchy/default/systemd/user/omarchy-crash-watch.service, omarchy-fcitx5.service, omarchy-sleep-lock.service). One nuance worth recording against the standing assumption that OMARCHY_PATH is only in ~/.bashrc: it also comes from /usr/share/uwsm/env.d/10-omarchy, which sources /usr/share/omarchy/default/bash/env-bootstrap, so a user unit in a live graphical session does see it. It is absent in a lingering or SSH-started user manager, which is the case the fix now covers. NOT exercised: creating, enabling, starting or reloading any unit, systemctl clean, loginctl enable-linger, WakeSystem=true, and any system-scope timer. Left symptom as written, since every shape it describes is reproducible, and left severity low and frequency common alone: the failure is a job that silently does not run, with no data loss, and it is a common self-inflicted mistake rather than a distro defect.

The cause above was rewritten on 2026-09-11 to match this note; the fix was corrected by the audit itself.
RISK

WakeSystem=true requires privileges and is generally only available in the system service manager, so a systemctl --user timer cannot use it at all. Even in the system manager it needs hardware that supports a timed wake, because it switches the timer to CLOCK_BOOTTIME_ALARM or CLOCK_REALTIME_ALARM. When it fails, the timer does not merely skip a run, it goes dead: the journal shows a Failed to add monotonic event source or Failed to add realtime event source warning and then Failed with result 'resources'. Do not add it speculatively. Enabling lingering keeps your user instance and its services running after logout. It is not a substitute for autologin, and using it that way breaks anything that needs the session: a lingering user manager has no graphical session, so WAYLAND_DISPLAY and OMARCHY_PATH are unset and a unit that needs either starts and then fails instead of waiting.

Symptom

A timer is "enabled" but the job never runs. systemctl --user list-timers shows NEXT as n/a or -, or LAST never advances. Sometimes systemctl --user enable foo.timer was run and nothing happened at all until the next login, or the OnCalendar= expression turns out to mean something completely different from what was intended.

Cause

Four traps, and the first three are about how the timer is installed. (1) systemctl enable only creates the symlink. It does not start the timer, so nothing arms until the next boot or login, and --now does both. (2) A timer with no WantedBy=timers.target in [Install] cannot be enabled into anything. (3) OnCalendar= syntax is easy to get subtly wrong, and a malformed expression is logged and ignored, leaving the timer loaded with no trigger at all. (4) A timer built only from monotonic directives (OnBootSec=, OnActiveSec=, OnStartupSec=, OnUnitActiveSec=, OnUnitInactiveSec=) can end up with no next elapse and show NEXT as - indefinitely, and Persistent=true does not rescue it, because Persistent= only has an effect on timers configured with OnCalendar=.

Fix

See what is actually armed, including inactive timers:


systemctl --user list-timers --all
systemctl list-timers --all          # system timers
systemctl --user cat foo.timer

A NEXT of - means the timer has no next elapse. Read the raw value to be sure, since the table abbreviates:


systemctl --user show foo.timer -p NextElapseUSecRealtime -p NextElapseUSecMonotonic -p LastTriggerUSec

NextElapseUSecMonotonic=infinity with an empty NextElapseUSecRealtime is the "never fires again" state.

Make sure the timer has an install target, and give it a calendar trigger rather than only monotonic ones if it must survive a restart of your user manager:


# ~/.config/systemd/user/foo.timer
[Unit]
Description=Run foo daily

[Timer]
OnCalendar=*-*-* 04:00:00
Persistent=true
RandomizedDelaySec=10m
AccuracySec=1m
Unit=foo.service

[Install]
WantedBy=timers.target

Persistent=true catches up a run missed while the machine was off, but only for OnCalendar= timers. On a timer built from OnBootSec= and OnUnitActiveSec= alone it does nothing.

Then enable *and* start:


systemctl --user daemon-reload
systemctl --user enable --now foo.timer
systemctl --user list-timers foo.timer

Test the calendar expression before trusting it. This is the single most useful command here:


systemd-analyze calendar "*-*-* 04:00:00"
systemd-analyze calendar --iterations=5 "Mon..Fri 22:30"
systemd-analyze calendar weekly

It prints Normalized form and the next elapse times. A syntax error is reported instead, and the command exits non-zero:


$ systemd-analyze calendar "*-*-* 25:00:00"
Failed to parse calendar specification '*-*-* 25:00:00': Invalid argument

The weekday field is optional, and if you use it you must name at least one weekday, so *-*-* 4:00:00 normalizes to *-*-* 04:00:00 and means every day at 4am, while Mon,Tue *-*-01..04 12:00:00 means the 1st to the 4th of the month but only if that day is a Monday or a Tuesday.

Run the service by hand to prove the job itself works, independently of scheduling:


systemctl --user start foo.service
journalctl --user -u foo.service -n 50 --no-pager

If the timer has drifted or thinks it already ran, clear its stamp file. systemctl clean is the documented way, and it requires the unit to be stopped first:


systemctl --user stop foo.timer
systemctl --user clean --what=state foo.timer
systemctl --user start foo.timer

The stamp is a zero-length file whose mtime is the last trigger, so you can look at it and delete it by hand if you prefer:


ls -l ~/.local/share/systemd/timers/
rm ~/.local/share/systemd/timers/stamp-foo.timer

(System timers keep stamps in /var/lib/systemd/timers/.)

Remember that a **user** timer only exists while your user instance does. It stops at logout unless you enable lingering:


loginctl enable-linger
loginctl list-users

If the job needs the graphical session (a notification, a screenshot, a hyprctl call), the service needs the session's environment, not just a trigger. On Omarchy 4 that environment arrives late: /usr/share/omarchy/default/hypr/autostart.lua runs systemctl --user import-environment and dbus-update-activation-environment --systemd --all at hyprland.start, so WAYLAND_DISPLAY is absent from the user manager until the session is up and absent for good in a lingering or SSH-started user manager. Copy the shape Omarchy uses for its own units, which is to order the service after the target, tie its lifetime to it, and refuse to start without the variable:


# ~/.config/systemd/user/foo.service
[Unit]
After=graphical-session.target
PartOf=graphical-session.target
ConditionEnvironment=WAYLAND_DISPLAY

Keep the timer itself on timers.target, or move it to WantedBy=graphical-session.target if it should exist only while you are logged in.

Calling an omarchy command from a user unit needs one more check. During a graphical session OMARCHY_PATH is in the user manager environment, because /usr/share/uwsm/env.d/10-omarchy sources /usr/share/omarchy/default/bash/env-bootstrap, and systemctl --user show-environment | grep OMARCHY_PATH shows it. In a lingering or SSH-started user manager it is not there, and a unit sources no profile of its own. Use the absolute path, as Omarchy's own units do:


ExecStart=/usr/bin/omarchy-something

If the script genuinely needs the variable, use a login shell instead:


ExecStart=/bin/bash -lc 'omarchy-something'

Verify

systemctl --user list-timers foo.timer shows a concrete NEXT timestamp and, after it passes, a LAST timestamp. journalctl --user -u foo.service shows the run.

Sources

user-timer-oncalendar-never-fires