hermes-agent/website/docs/guides/cron-troubleshooting.md

sidebar_position	title	description
12	Cron Troubleshooting	Diagnose and fix common Hermes cron issues — jobs not firing, delivery failures, skill loading errors, and performance problems

Cron Troubleshooting

When a cron job isn't behaving as expected, work through these checks in order. Most issues fall into one of four categories: timing, delivery, permissions, or skill loading.

---

Jobs Not Firing

Check 1: Verify the job exists and is active

hermes cron list

Look for the job and confirm its state is [active] (not [paused] or [completed]). If it shows [completed], the repeat count may be exhausted — edit the job to reset it.

Check 2: Confirm the schedule is correct

A misformatted schedule silently defaults to one-shot or is rejected entirely. Test your expression:

Your expression	Should evaluate to
0 9 * * *	9:00 AM every day
0 9 * * 1	9:00 AM every Monday
every 2h	Every 2 hours from now
30m	30 minutes from now
2025-06-01T09:00:00	June 1, 2025 at 9:00 AM UTC

If the job fires once and then disappears from the list, it's a one-shot schedule (30m, 1d, or an ISO timestamp) — expected behavior.

Check 3: Is the gateway running?

Cron jobs are fired by the gateway's background ticker thread, which ticks every 60 seconds. A regular CLI chat session does not automatically fire cron jobs.

If you're expecting jobs to fire automatically, you need a running gateway (hermes gateway for foreground, or hermes gateway start for the installed service). For one-off debugging, you can manually trigger a tick with hermes cron tick.

Check 4: Check the system clock and timezone

Jobs use the local timezone. If your machine's clock is wrong or in a different timezone than expected, jobs will fire at the wrong times. Verify:

date
hermes cron list   # Compare next_run times with local time

---

Delivery Failures

Check 1: Verify the deliver target is correct

Delivery targets are case-sensitive and require the correct platform to be configured. A misconfigured target silently drops the response.

Target	Requires
telegram	TELEGRAM_BOT_TOKEN in ~/.hermes/.env
discord	DISCORD_BOT_TOKEN in ~/.hermes/.env
slack	SLACK_BOT_TOKEN in ~/.hermes/.env
whatsapp	WhatsApp gateway configured
signal	Signal gateway configured
matrix	Matrix homeserver configured
email	SMTP configured in config.yaml
sms	SMS provider configured
local	Write access to ~/.hermes/cron/output/
origin	Delivers to the chat where the job was created

Other supported platforms include mattermost, homeassistant, dingtalk, feishu, wecom, weixin, bluebubbles, qqbot, and webhook. You can also target a specific chat with platform:chat_id syntax (e.g., telegram:-1001234567890).

If delivery fails, the job still runs — it just won't send anywhere. Check hermes cron list for updated last_error field (if available).

Check 2: Check [SILENT] usage

If your cron job produces no output or the agent responds with [SILENT], delivery is suppressed. This is intentional for monitoring jobs — but make sure your prompt isn't accidentally suppressing everything.

A prompt that says "respond with [SILENT] if nothing changed" will silently swallow non-empty responses too. Check your conditional logic.

Check 3: Platform token permissions

Each messaging platform bot needs specific permissions to receive messages. If delivery silently fails:

• Telegram: Bot must be an admin in the target group/channel
• Discord: Bot must have permission to send in the target channel
• Slack: Bot must be added to the workspace and have chat:write scope

Check 4: Response wrapping

By default, cron responses are wrapped with a header and footer (cron.wrap_response: true in config.yaml). Some platforms or integrations may not handle this well. To disable:

cron:
  wrap_response: false

---

Skill Loading Failures

Check 1: Verify skills are installed

hermes skills list

Skills must be installed before they can be attached to cron jobs. If a skill is missing, install it first with hermes skills install <skill-name> or via /skills in the CLI.

Check 2: Check skill name vs. skill folder name

Skill names are case-sensitive and must match the installed skill's folder name. If your job specifies ai-funding-daily-report but the skill folder is ai-funding-daily-report, confirm the exact name from hermes skills list.

Check 3: Skills that require interactive tools

Cron jobs run with the cronjob, messaging, and clarify toolsets disabled. This prevents recursive cron creation, direct message sending (delivery is handled by the scheduler), and interactive prompts. If a skill relies on these toolsets, it won't work in a cron context.

Check the skill's documentation to confirm it works in non-interactive (headless) mode.

Check 4: Multi-skill ordering

When using multiple skills, they load in order. If Skill A depends on context from Skill B, make sure B loads first:

/cron add "0 9 * * *" "..." --skill context-skill --skill target-skill

In this example, context-skill loads before target-skill.

---

Job Errors and Failures

Check 1: Review recent job output

If a job ran and failed, you may see error context in:

1. The chat where the job delivers (if delivery succeeded)
2. ~/.hermes/logs/agent.log for scheduler messages (or errors.log for warnings)
3. The job's last_run metadata via hermes cron list

Check 2: Common error patterns

"No such file or directory" for scripts The script path must be an absolute path (or relative to the Hermes config directory). Verify:

ls ~/.hermes/scripts/your-script.py   # Must exist
hermes cron edit <job_id> --script ~/.hermes/scripts/your-script.py

"Skill not found" at job execution The skill must be installed on the machine running the scheduler. If you move between machines, skills don't automatically sync — reinstall them with hermes skills install <skill-name>.

Job runs but delivers nothing Likely a delivery target issue (see Delivery Failures above) or a silently suppressed response ([SILENT]).

Job hangs or times out The scheduler uses an inactivity-based timeout (default 600s, configurable via HERMES_CRON_TIMEOUT env var, 0 for unlimited). The agent can run as long as it's actively calling tools — the timer only fires after sustained inactivity. Long-running jobs should use scripts to handle data collection and deliver only the result.

Check 3: Lock contention

The scheduler uses file-based locking to prevent overlapping ticks. If two gateway instances are running (or a CLI session conflicts with a gateway), jobs may be delayed or skipped.

Kill duplicate gateway processes:

ps aux | grep hermes
# Kill duplicate processes, keep only one

Check 4: Permissions on jobs.json

Jobs are stored in ~/.hermes/cron/jobs.json. If this file is not readable/writable by your user, the scheduler will fail silently:

ls -la ~/.hermes/cron/jobs.json
chmod 600 ~/.hermes/cron/jobs.json   # Your user should own it

---

Performance Issues

Slow job startup

Each cron job creates a fresh AIAgent session, which may involve provider authentication and model loading. For time-sensitive schedules, add buffer time (e.g., 0 8 * * * instead of 0 9 * * *).

Too many overlapping jobs

The scheduler executes jobs sequentially within each tick. If multiple jobs are due at the same time, they run one after another. Consider staggering schedules (e.g., 0 9 * * * and 5 9 * * * instead of both at 0 9 * * *) to avoid delays.

Large script output

Scripts that dump megabytes of output will slow down the agent and may hit token limits. Filter/summarize at the script level — emit only what the agent needs to reason about.

---

Diagnostic Commands

hermes cron list                    # Show all jobs, states, next_run times
hermes cron run <job_id>            # Schedule for next tick (for testing)
hermes cron edit <job_id>           # Fix configuration issues
hermes logs                         # View recent Hermes logs
hermes skills list                  # Verify installed skills

---

Getting More Help

If you've worked through this guide and the issue persists:

1. Run the job with hermes cron run <job_id> (fires on next gateway tick) and watch for errors in the chat output
2. Check ~/.hermes/logs/agent.log for scheduler messages and ~/.hermes/logs/errors.log for warnings
3. Open an issue at github.com/NousResearch/hermes-agent with:
   • The job ID and schedule
   • The delivery target
   • What you expected vs. what happened
   • Relevant error messages from the logs

---

For the complete cron reference, see Automate Anything with Cron and Scheduled Tasks (Cron).