Troubleshoot Hermes Cron Jobs End to End

Cron problems usually belong to one of four layers: scheduling, execution, delivery, or prerequisites. Diagnose them in that order so a messaging symptom does not hide a scheduler problem—or vice versa.

Prove the scheduler path

Start with hermes cron list. Confirm the job exists, is active, has a future next_run, and has not exhausted a one-shot or repeat count. Compare the local clock and timezone with the schedule. Duration and ISO schedules may be one-shot; five-field cron expressions repeat.

A running gateway owns the background ticker. An ordinary CLI chat does not fire jobs automatically. Use hermes gateway status, then hermes cron run <job_id> to queue a controlled test for the next tick. Review ~/.hermes/logs/agent.log, errors.log, and the job's latest metadata.

Separate execution from delivery

A job may finish successfully while delivery fails. Verify the exact platform target, channel identifier, bot permissions, and credentials. [SILENT] suppresses delivery and must be the entire quiet response; do not mix it into a report. Local delivery also requires write access to the cron output directory.

Skills must be installed under the exact configured names and usable without interaction. Cron disables recursive scheduling, direct messaging tools, and clarification prompts. Scripts should use absolute paths, and large pre-run output should be filtered before it reaches the agent.

Diagnostic checklist

Confirm active state, schedule type, timezone, and next run.
Confirm one healthy gateway owns the ticker.
Queue one test with hermes cron run <job_id>.
Check execution logs before changing delivery settings.
Verify platform permissions and the exact destination.
Confirm attached skills work headlessly and load in order.
Stagger jobs that are due on the same minute.

Pitfalls

Multiple gateway instances can contend for scheduler locks. A paused or completed job will not fire. Jobs due together execute sequentially and may appear late. Inactivity timeouts measure sustained agent silence, not necessarily total wall time. Avoid changing several layers at once; that destroys the evidence needed to identify the fault.

Verification steps

Trigger one job manually and record its run metadata.
Confirm the agent produced a nonempty final response.
Verify the destination received that exact run, not an older message.
Leave the gateway running through one natural scheduled occurrence.
Recheck logs after the next tick for delayed warnings.

Use the official Cron Troubleshooting guide for the latest commands and platform notes.