Skip to main content

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​

minerva 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​

An unrecognized schedule is rejected with an error listing the accepted forms. A recognized one can still mean something other than you intended — check what your expression evaluates to:

Your expressionShould evaluate to
0 9 * * *9:00 AM every day
0 9 * * 19:00 AM every Monday
every 2hEvery 2 hours from now
30mEvery 30 minutes (a bare duration is a recurring interval, same as every 30m)
in 30mOnce, 30 minutes from now
2025-06-01T09:00:00Once, June 1, 2025 at 9:00 AM in your configured Minerva timezone

If the job fires once and then disappears from the list, it's a one-shot schedule (in 30m, in 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 (minerva gateway for foreground, or minerva gateway start for the installed service). For one-off debugging, you can manually trigger a tick with minerva cron tick.

Desktop app: the desktop's primary backend runs its own ticker, and it ticks every local profile's cron store — so jobs on a secondary profile keep firing even while that profile's backend is asleep (the desktop puts idle profile backends to sleep after ~10 minutes). You do not need to keep a profile open for its scheduled jobs to run.

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
minerva 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.

TargetRequires
telegramTELEGRAM_BOT_TOKEN in ~/.minerva/.env
discordDISCORD_BOT_TOKEN in ~/.minerva/.env
slackSLACK_BOT_TOKEN in ~/.minerva/.env
localWrite access to ~/.minerva/cron/output/
originDelivers to the chat where the job was created

webhook is also a supported target. 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 minerva cron list for updated last_error field (if available).

Check 2: Check [SILENT] usage​

If your cron job produces no output, delivery is suppressed. If the agent response includes the cron quiet marker [SILENT], delivery is also suppressed. This is intentional for monitoring jobs — but make sure your prompt is not accidentally suppressing everything.

Use prompts like "respond with only [SILENT] if nothing changed." Avoid asking the agent to include [SILENT] inside a longer explanation, because cron treats that marker as a suppression signal.

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​

minerva skills list

Skills must be installed before they can be attached to cron jobs. If a skill is missing, install it first with minerva 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-report but the skill folder is ai-funding-daily-report, confirm the exact name from minerva skills list.

Check 3: Skills that require interactive tools​

Cron jobs run with the cronjob and clarify toolsets disabled (cronjob stays available when cron.allow_agent_scheduling: true). This prevents recursive cron creation and interactive prompts; delivery is handled by the scheduler. 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. ~/.minerva/logs/agent.log for scheduler messages (or errors.log for warnings)
  3. The job's last_run metadata via minerva cron list

Check 2: Common error patterns​

"No such file or directory" for scripts The script path is relative to ~/.minerva/scripts/ — absolute and ~/ paths are rejected. Verify:

ls ~/.minerva/scripts/your-script.py   # Must exist
minerva cron edit <job_id> --script 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 minerva skills install <skill-name>.

Job runs but delivers nothing Likely a delivery target issue (see Delivery Failures above), no output, or a response containing the cron quiet marker [SILENT].

Job hangs or times out The scheduler uses an inactivity-based timeout (default 600s, configurable via MINERVA_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 minerva
# Kill duplicate processes, keep only one

Check 4: Permissions on jobs.json​

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

ls -la ~/.minerva/cron/jobs.json
chmod 600 ~/.minerva/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​

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

Getting More Help​

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

  1. Run the job with minerva cron run <job_id> (fires on next gateway tick) and watch for errors in the chat output
  2. Check ~/.minerva/logs/agent.log for scheduler messages and ~/.minerva/logs/errors.log for warnings
  3. Report it to the maintainers 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).