cron-parser

Overview

Cron expressions are write-only for most people — everyone copies them, few can read them. But misreading a schedule means backups that never run or jobs that fire 60x too often. This skill makes cron legible: the five fields, special strings, the day-of-month/day-of-week gotcha, and debugging techniques for "why didn't it run?"

When to use

• Writing cron schedules for jobs and automation

• Reading and understanding existing cron expressions

• Debugging jobs that run at wrong times (or not at all)

• Choosing between cron and modern schedulers

• Documenting schedules for teams

Core concepts

• • The five fields. minute hour day-of-month month day-of-week — in that order. 30 2 * * * = 2:30 AM daily. Memorize the order with: "my happy dog makes dinner" (minute, hour, dom, month, dow) or just drill it until it's reflex.
• • Field syntax. * (every), */15 (every 15), 1,15 (list), 1-5 (range, Mon-Fri for dow), 9-17/2 (every 2 hours 9-5). Ranges and steps compose; lists don't take steps in classic cron.
• • The DOM/DOW trap. When both day-of-month and day-of-week are restricted (not *), cron runs when EITHER matches — not both. 0 0 1 * 1 runs on the 1st of the month AND every Monday. This surprises everyone once.
• • Special strings. @reboot, @yearly, @monthly, @weekly, @daily, @hourly — readable shorthands. Note: @reboot behavior varies (and doesn't exist in all cron implementations).
• • Environment minimalism. Cron runs with a sparse environment: minimal PATH, no shell profile. The #1 "works manually, fails in cron" cause is PATH — use absolute paths for everything or set PATH explicitly in the crontab.
• • Cron flavors differ. Vixie cron (classic Linux), cronie, systemd timers (the modern Linux alternative — more features, logging built in), and cloud schedulers (CloudWatch Events, Cloud Scheduler) all have quirks. @reboot, seconds fields, and timezone handling vary — check your implementation.

Practical workflow

1. 1. Write it plainly first. "Every weekday at 9:30 AM" → then translate: 30 9 * * 1-5. Describe in words before encoding — the words are the spec you'll verify against.

2. Use the field table. Build expressions field by field:

   • minute (0-59), hour (0-23), dom (1-31), month (1-12), dow (0-7, both 0 and 7 = Sunday)

   • Verify each field independently before combining.

3. Common patterns (verify against your cron flavor):

   • */5 * * * * — every 5 minutes

   • 0 * * * * — hourly

   • 0 2 * * * — daily 2 AM

   • 0 9 * * 1 — Mondays 9 AM

   • 0 0 1 * * — first of month midnight

   • 30 9 * * 1-5 — weekdays 9:30 AM

   • 0 0 * * 0 — Sundays midnight

4. 4. Debug non-running jobs. Checklist: is the cron daemon running? Is the crontab installed for the right user (crontab -l)? Absolute paths everywhere? Environment variables set? Permissions on the script (executable)? Output captured (redirect stdout/stderr to a log — silent failures are cron's default)? Timezone correct (system vs expected)?
5. 5. Log everything. 30 2 * * * /opt/job.sh >> /var/log/job.log 2>&1 — without output capture, failures vanish. Better: have the job log itself with timestamps.
6. 6. Consider alternatives. Need seconds precision, dependencies, retries, or observability? Cron is the wrong tool — use systemd timers, or a proper scheduler (Airflow/Temporal for workflows, cloud schedulers for cloud). Cron is for simple, independent, minute-granularity jobs.

Common pitfalls

• • The DOM/DOW OR trap. 0 0 1 * 1 doesn't mean "first Monday" — it means "1st AND Mondays." For "first Monday," you need wrapper logic in the script.
• • Timezone confusion. Cron uses system local time (usually). DST transitions cause skipped or doubled runs. For UTC-critical jobs, set CRON_TZ (where supported) or run the system in UTC.
• • Environment assumptions. python resolving via PATH, ~ expansion, locale settings — all differ under cron. Absolute paths, explicit env vars, tested in a clean shell.
• • Overlapping runs. A job that takes 70 minutes on an hourly schedule stacks up. Use file locks (flock) to prevent concurrent runs.
• • Silent failures. No output redirection = no evidence. Every cron job should log somewhere you'll actually check — or alert on failure.
• • Editing the wrong crontab. User crontab vs system /etc/crontab (which has an extra user field) vs /etc/cron.d/. The 6-field system format in a 5-field user crontab breaks mysteriously.