In this lesson, you will learn how to use systemctl to diagnose why your systemd timers are failing to trigger as expected.
When a scheduled task fails under systemd, it rarely leaves a trail as simple as a cron log entry. Instead, the failure is often split between the timer unit itself and the service unit it is supposed to trigger. Debugging requires a two-pronged approach using systemctl.
Checking Timer Status
First, examine the timer's health. The command systemctl list-timers provides a high-level overview, but for deep debugging, query the specific unit:
systemctl status my-task.timer
Look for the Last passed and Next fields. If the Next field indicates the time has already passed but the task hasn't run, the timer is likely stuck or its dependency is masked. Pay close attention to the Active: line; if it shows inactive (dead) instead of active (waiting), the timer was never started or has crashed.
Inspecting Execution Logic
If the timer appears active, the issue often lies within the service unit being triggered. Systemd timers do not run scripts directly; they trigger a service unit. To see why the execution failed, check the logs of the service itself rather than the timer:
journalctl -u my-task.service --since "1 hour ago"
If you see Result: exit-code, check the ExecStart command path within your unit file. A common failure mode occurs when the environment variables expected by the script are missing (a concept we touched on previously with environment isolation). You can verify if the service is even capable of launching by manually triggering it:
systemctl start my-task.service
If this command fails, the issue is with your task's logic or permissions, not the timing logic. If it succeeds manually but fails automatically, inspect the Condition* or Assert* directives in your unit file, as these can silently prevent a timer from launching the service.
Key Takeaway: To debug a failed timer, isolate the failure by checking if the timer unit is actually "waiting" and then using journalctl on the triggered service unit to identify the specific exit code or environment error.