How to Troubleshoot systemd Timers: 7 Practical Checks

First, find out which part failed

A systemd timer tells Linux when to start work. A service unit tells systemd what to run. The program then succeeds, fails, or produces an unexpected result. Troubleshooting systemd timers as separate stages saves time.

Quick answer: If a systemd timer is not running a task, first inspect the .timer with systemctl status and systemctl list-timers --all. Then inspect the matching .service and its journalctl entries. Check the calendar expression, unit names, exit status and execution environment before making changes.

The commands below use sa-timer-demo.timer and sa-timer-demo.service from the preceding practice lesson. They are example names, not systemd built-ins. Replace them with the exact units on your machine. The initial checks are read-only; a later manual start is clearly marked as an action.

Start with the scheduler, not with a restart. A timer may be installed but disabled, enabled for future boots but inactive now, or not loaded at all. These states are different, and they are the first clues when systemd timers stop triggering work.

systemctl status sa-timer-demo.timer --no-pager -l
systemctl is-enabled sa-timer-demo.timer
systemctl is-active sa-timer-demo.timer

Look for the Loaded and Active lines. enabled describes whether the timer is configured to start automatically; active describes its state now. Neither proves that the service ran successfully.

A healthy timer can still run later than you expect. First inspect the next and last trigger timestamps, then compare the schedule in the actual unit file with the system clock.

systemctl list-timers --all sa-timer-demo.timer
systemctl cat sa-timer-demo.timer
timedatectl status
systemd-analyze calendar --iterations=3 '*-*-* *:00/5:00'

The final command parses the five-minute example from Lesson 02; it does not read your live timer automatically. For another schedule, copy its actual OnCalendar= value into the calendar command. A calendar expression describes wall-clock times; the machine’s timezone and clock matter when diagnosing systemd timers.

By default, example.timer activates example.service. But a timer can override that relationship with Unit=. If you inspect the wrong service, you may conclude nothing ran even when systemd timers activated a different target.

systemctl cat sa-timer-demo.timer
systemctl cat sa-timer-demo.service
systemctl list-timers --all sa-timer-demo.timer

Read the ACTIVATES column when it is available, and compare it with the timer’s Unit= setting. Check that the service exists and points to the intended executable.

Now inspect the workload itself. For a typical Type=oneshot job, inactive (dead) after completion can be completely normal. You need the last result, exit information and matching journal messages.

systemctl status sa-timer-demo.service --no-pager -l
systemctl show sa-timer-demo.service -p ActiveState -p Result -p ExecMainStatus

A nonzero exit status or a failed unit is a reason to investigate. Result=success describes the service manager’s recorded result—not proof that a backup file is valid or that a notification reached its destination. Check the real output separately; systemd timers cannot verify application-level results for you.

The numeric exit statuses are systemd execution status names, not universal application exit codes. See systemd.exec(5) for the complete list.

Instead of reading unrelated system messages, narrow the journal to this service and the time window when the problem occurred. Look for the first useful error before the final failed status.

sudo journalctl -u sa-timer-demo.service -b --since "-2 hours" --no-pager -o short-iso
sudo journalctl -u sa-timer-demo.timer -b -n 30 --no-pager

The first command shows service entries from the current boot within the last two hours. The second examines timer-unit messages, if any were recorded. A quiet timer journal does not, by itself, prove that no trigger occurred. If the service prints useful information to stdout or stderr and journal capture is configured, its journal is usually the stronger clue when systemd timers seem silent.

For investigation across restarts, repeat the service query without -b and choose a wider date range. Older entries may not be present when the journal is volatile, rotated or otherwise unavailable. If you need a detailed guide to filters, see journalctl Explained .

If the timer definition and service logs still do not settle the question, verify the unit files. This check does not start the service or modify the schedule.

sudo systemd-analyze verify /etc/systemd/system/sa-timer-demo.timer /etc/systemd/system/sa-timer-demo.service
ls -l /usr/local/bin/sa-timer-demo.sh
systemctl cat sa-timer-demo.service

For the read-only demonstration script from Lesson 02, you may then start the service manually to separate a script failure from a scheduling failure. Do not do this with backups, migrations, payments or destructive maintenance scripts until you know the consequences of a second run.

sudo systemctl start sa-timer-demo.service
sudo journalctl -u sa-timer-demo.service -n 20 --no-pager

In the demo, look for the line beginning with sa-timer-demo: executed at. If the manual start works but the scheduled event does not happen, return to the timer state and next-trigger checks. If the manual start fails, examine the service configuration, script permissions, paths and runtime environment first.

A timer can be correctly configured yet not run while the machine is shut down. The important question is what you expect from systemd timers when the machine comes back online.

A machine turned off for three scheduled daily occurrences does not automatically replay three separate runs on startup just because Persistent=true is set. The stored trigger state may cause an activation after the timer comes online; the service still needs to finish successfully.

This topic is introduced in Lesson 01 and specified in the systemd.timer(5) manual . If the schedule is too frequent for the workload duration, revisit the task design instead of assuming every interval must produce another concurrent process.

Choose the next check from the symptom

Use this as a practical decision table when someone says “the systemd timer is not working.” When troubleshooting systemd timers, start with evidence; change configuration only after identifying a specific problem.

A short hypothetical investigation

Illustrative scenario · not a reported production incident or tested server

Situation: A student sets up the disposable five-minute sa-timer-demo from Lesson 02. At the end of the lab, the timer says active (waiting), but the student cannot find a fresh output line in the journal.

Check 1: systemctl list-timers --all sa-timer-demo.timer shows a future NEXT time. That is evidence the timer is waiting—not that its service has already finished.

Check 2: systemctl cat sa-timer-demo.timer shows the target sa-timer-demo.service. The student verifies the service independently using the safe manual test.

Check 3: if the service prints the expected sa-timer-demo: executed at... line when started manually, the script itself is probably not the immediate issue. They wait for the next scheduled window, allow for AccuracySec, then inspect recent service entries. If the manual test instead returns a failure, they investigate that error before changing the timer.

Takeaway: one status screen cannot answer every question. For systemd timers, timer state establishes scheduling; service status and journal messages establish execution. The missing line might be a timing misunderstanding, a service failure, or a logging query that was too narrow.

Check your understanding