Introduction
# Cron Job Reliability Guide
A comprehensive guide to diagnosing and fixing cron job issues in Clawdbot/Moltbot. This skill documents common failure patterns and their solutions, learned through production debugging.
## When to Use This Skill
Use this skill when: - Scheduled messages aren't being delivered - Cron jobs show "error" status - Messages arrive at wrong times (timezone issues) - The agent times out when using the `cron` tool - Fallback models ignore instructions and call tools unexpectedly
## Quick Reference
### The Golden Rule
**Always use these flags together for reliable delivery:**
```bash clawdbot cron add \ --name "my-job" \ --cron "0 9 * * 1-5" \ --tz "America/New_York" \ --session isolated \ --message "[INSTRUCTION: DO NOT USE ANY TOOLS] Your prompt here" \ --deliver --channel telegram --to "CHAT_ID" \ --best-effort-deliver ```
### Essential Flags Explained
| Flag | Purpose | Why It Matters | |------|---------|----------------| | `--session isolated` | Creates dedicated session | Prevents message loss in busy conversations | | `--tz "TIMEZONE"` | Sets explicit timezone | Avoids UTC confusion | | `--deliver` | Sends to channel | Required for Telegram/WhatsApp | | `--best-effort-deliver` | Don't fail on delivery error | Graceful degradation |
---
## Problem 1: Internal `cron` Tool Deadlock
### Symptoms - Agent times out (10s) when calling `cron list` or `cron add` - Error: "Tool execution timed out" - Gateway logs show 80s+ response times
### Root Cause The internal `cron` tool creates a deadlock between the agent process and gateway.
### Solution **Never use the `cron` tool directly.** Use `exec` (or `bash`) instead:
```bash # CORRECT - uses exec to bypass deadlock exec: clawdbot cron list exec: clawdbot cron add --name "reminder" --at "+5m" --message "Hello"
# INCORRECT - causes timeout cron list # DO NOT USE cron add ... # DO NOT USE ```
### For Agents If you're an AI agent reading this: when the user asks you to manage cron jobs, **always use the exec/bash tool** to run `clawdbot cron` commands. Never invoke the `cron` tool directly.
---
## Problem 2: Messages Not Delivered
### Symptoms - Job shows "ok" status but message never arrives - Works in testing but fails on schedule - Intermittent delivery
### Root Cause Using `--session main` or `--system-event` causes messages to get lost when there's an active conversation in the main session.
### Solution **Always use `--session isolated`:**
```bash # CORRECT - isolated session, guaranteed delivery clawdbot cron add \ --name "daily-standup" \ --cron "0 9 * * 1-5" \ --session isolated \ --deliver --channel telegram --to "-100XXXXXXXXXX"
# INCORRECT - messages can be lost clawdbot cron add \ --name "daily-standup" \ --session main \ --system-event \ ... ```
### Verification After creating a job, test it:
```bash # Run the job immediately to verify delivery clawdbot cron run <job-id> ```
---
## Problem 3: Wrong Execution Time
### Symptoms - Job runs 4-5 hours early or late - Schedule shows correct time but execution is off - Works correctly sometimes, fails other times
### Root Cause Missing timezone specification defaults to UTC.
### Solution **Always specify timezone explicitly:**
```bash # CORRECT - explicit timezone clawdbot cron add \ --cron "0 9 * * 1-5" \ --tz "America/New_York" \ ...
# INCORRECT - defaults to UTC clawdbot cron add \ --cron "0 9 * * 1-5" \ ... ```
### Common Timezone IDs
| Region | Timezone ID | |--------|-------------| | US Eastern | `America/New_York` | | US Pacific | `America/Los_Angeles` | | UK | `Europe/London` | | Central Europe | `Europe/Berlin` | | India | `Asia/Kolkata` | | Japan | `Asia/Tokyo` | | Australia Eastern | `Australia/Sydney` | | Brazil | `America/Sao_Paulo` | | Bolivia | `America/La_Paz` |
---
## Problem 4: Fallback Models Ignore Instructions
### Symptoms - Primary model works correctly - When fallback activates, agent calls tools unexpectedly - Agent tries to use `exec`, `read`, or other tools when it shouldn't
### Root Cause Some fallback models (especially smaller/faster ones) don't follow system instructions as strictly as primary models.
### Solution **Embed instructions directly in the message:**
```bash # CORRECT - instruction embedded in message clawdbot cron add \ --message "[INSTRUCTION: DO NOT USE ANY TOOLS. Respond with text only.] Generate a motivational Monday message for the team."
# INCORRECT - relies only on system prompt clawdbot cron add \ --message "Generate a motivational Monday message for the team." ```
### Robust Message Template
```text [INSTRUCTION: DO NOT USE ANY TOOLS. Write your response directly.]
Your actual prompt here. Be specific about what you want. ```
---
## Problem 5: Job Stuck in Error State
### Symptoms - Job status shows "error" - Subsequent runs also fail - No clear error message
### Diagnosis
```bash # Check job details clawdbot cron show <job-id>
# Check recent logs tail -100 /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log | grep -i cron
# Check gateway errors tail -50 ~/.clawdbot/logs/gateway.err.log ```
### Common Causes and Fixes
| Cause | Fix | |-------|-----| | Model quota exceeded | Wait for quota reset or switch model | | Invalid chat ID | Verify channel ID with `--to` | | Bot removed from group | Re-add bot to Telegram group | | Gateway not running | `clawdbot gateway restart` |
### Nuclear Option
If nothing works:
```bash # Remove the problematic job clawdbot cron rm <job-id>
# Restart gateway clawdbot gateway restart
# Recreate with correct flags clawdbot cron add ... (with all recommended flags) ```
---
## Debugging Commands
### View All Jobs
```bash clawdbot cron list ```
### Inspect Specific Job
```bash clawdbot cron show <job-id> ```
### Test Job Immediately
```bash clawdbot cron run <job-id> ```
### Check Logs
```bash # Today's logs filtered for cron tail -200 /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log | grep -i cron
# Gateway errors tail -100 ~/.clawdbot/logs/gateway.err.log
# Watch logs in real-time tail -f /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log | grep --line-buffered cron ```
### Restart Gateway
```bash clawdbot gateway restart ```
---
## Complete Working Examples
### Daily Standup Reminder (9 AM, Mon-Fri)
```bash clawdbot cron add \ --name "daily-standup-9am" \ --cron "0 9 * * 1-5" \ --tz "America/New_York" \ --session isolated \ --message "[INSTRUCTION: DO NOT USE ANY TOOLS. Write directly.]
Good morning team! Time for our daily standup.
Please share: 1. What did you accomplish yesterday? 2. What are you working on today? 3. Any blockers?
@alice @bob" \ --deliver --channel telegram --to "-100XXXXXXXXXX" \ --best-effort-deliver ```
### One-Shot Reminder (20 minutes from now)
```bash clawdbot cron add \ --name "quick-reminder" \ --at "+20m" \ --delete-after-run \ --session isolated \ --message "[INSTRUCTION: DO NOT USE ANY TOOLS.]
Reminder: Your meeting starts in 10 minutes!" \ --deliver --channel telegram --to "-100XXXXXXXXXX" \ --best-effort-deliver ```
### Weekly Report (Friday 5 PM)
```bash clawdbot cron add \ --name "weekly-report-friday" \ --cron "0 17 * * 5" \ --tz "America/New_York" \ --session isolated \ --message "[INSTRUCTION: DO NOT USE ANY TOOLS.]
Happy Friday! Time to wrap up the week.
Please share your weekly highlights and any items carrying over to next week." \ --deliver --channel telegram --to "-100XXXXXXXXXX" \ --best-effort-deliver ```
---
## Checklist for New Cron Jobs
Before creating any cron job, verify:
- [ ] Using `exec: clawdbot cron add` (not the `cron` tool directly) - [ ] `--session isolated` is set - [ ] `--tz "YOUR_TIMEZONE"` is explicit - [ ] `--deliver --channel CHANNEL --to "ID"` for message delivery - [ ] `--best-effort-deliver` for graceful failures - [ ] Message starts with `[INSTRUCTION: DO NOT USE ANY TOOLS]` - [ ] Tested with `clawdbot cron run <id>` after creation
---
## Related Resources
- [Clawdbot Cron Documentation](https://docs.molt.bot/tools/cron) - [Timezone Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) - [Cron Expression Generator](https://crontab.guru/)
---
*Skill authored by Isaac Zarzuri. Based on production debugging experience with Clawdbot/Moltbot.*