A reliable cron expression is more than a compact schedule: it is an operational rule that needs testing, ownership, time-zone decisions, logging, and a failure plan. This guide shows how to build a cron expression from plain language, check its edge cases, compare common syntax variants, and audit scheduled jobs before they become a source of missed work or duplicate processing.
Overview
Cron is a scheduler for recurring commands and tasks. A traditional cron expression normally contains five fields that describe the minute, hour, day of the month, month, and day of the week. The scheduler evaluates those fields and starts the associated command when the current time matches.
The basic five-field format is:
minute hour day-of-month month day-of-weekFor example:
30 2 * * *This describes a task scheduled for 02:30 every day in the scheduler's configured time zone. The asterisk means “every allowed value”. It does not, by itself, mean that the task runs immediately or continuously.
Before writing an expression, translate the requirement into five questions:
- Which minute or minutes should the task run?
- Which hour or hours are allowed?
- Which calendar days are included?
- Which months are included?
- Which weekdays are included?
Then verify the result with a cron expression generator, a local test harness, or the scheduler's own validation tool. A visual parser can help you understand an expression, but it should not replace testing against real dates, time zones, and execution behaviour.
What to track
Cron field reference
| Field | Typical values | Useful syntax | Example |
|---|---|---|---|
| Minute | 0–59 | Numbers, ranges, lists, steps | 0 |
| Hour | 0–23 | Numbers, ranges, lists, steps | 6-18 |
| Day of month | 1–31 | Numbers, ranges, lists, steps | 1,15 |
| Month | 1–12, sometimes names | Numbers, ranges, lists, steps | 1-6 |
| Day of week | Often 0–7 | Numbers, ranges, lists, sometimes names | 1-5 |
Common operators include:
- Asterisk (
*): every permitted value. - Comma (
,): a list, such as0,30for the start of each half-hour. - Hyphen (
-): an inclusive range, such as9-17. - Slash (
/): a step value, such as*/15for every 15 permitted units.
Names such as MON or JAN are supported by some implementations, but numeric values are often easier to move between systems. Day-of-week numbering also varies: many cron implementations accept both 0 and 7 for Sunday, while some hosted schedulers use a different convention or provide an additional seconds field. Always check the target scheduler's syntax before migrating an expression.
Useful cron syntax examples
| Requirement | Expression | Meaning |
|---|---|---|
| Every five minutes | */5 * * * * | At every five-minute interval |
| At the top of every hour | 0 * * * * | At minute zero of each hour |
| Every day at 01:15 | 15 1 * * * | Daily at 01:15 |
| Weekdays at 09:00 | 0 9 * * 1-5 | Monday through Friday at 09:00 where 1–5 represent weekdays |
| First day of each month at 04:00 | 0 4 1 * * | At 04:00 on day one of every month |
| Twice daily | 0 8,20 * * * | At 08:00 and 20:00 each day |
| Every 15 minutes during office hours | */15 9-17 * * 1-5 | Every 15 minutes during the selected weekday hours |
These examples assume standard five-field cron and a conventional day-of-week mapping. They are starting points, not universal guarantees.
What an audit should record
For every scheduled job, record the owner, purpose, command or endpoint, environment, scheduler, time zone, expression, expected duration, and destination of logs. Also record whether a second run is safe if the first run is still active. A short description such as “refresh reporting data” is not enough; document the input window, output location, and what a successful run looks like.
Cadence and checkpoints
Use a repeatable workflow whenever you add or change a schedule.
- Write the plain-language requirement. State the exact time zone, date range, and intended frequency. “Every morning” is incomplete if the business operates across regions.
- Build the expression field by field. Start with the least ambiguous fields, then add ranges, lists, or steps only where needed. Avoid clever shorthand that another operator may misread.
- Generate upcoming run times. Inspect at least the next several occurrences, including a month boundary when the job uses calendar dates.
- Test boundary conditions. Check February, months with fewer than 31 days, weekends, daylight-saving transitions, and the end of the selected hour range.
- Run the command independently. A valid cron expression does not prove that the command has the right working directory, environment variables, permissions, credentials, or network access.
- Deploy with observability. Capture start time, finish time, exit status, duration, and a useful run identifier. Send failures to an alert route that someone owns.
- Review after the first real runs. Confirm that the observed schedule matches the requirement and that the job finishes before its next possible invocation.
Platform syntax comparison
Traditional Unix-like cron commonly uses five fields. Some cron variants add a sixth field for seconds, while application frameworks, CI systems, container platforms, and cloud scheduler services may add their own features such as named time zones, a required seconds field, special modifiers, or a separate schedule format. A hosted service may interpret the expression in UTC by default even when the operator expects local time.
Before copying an expression between platforms, check four items in the destination documentation: field count and order, allowed ranges and names, day-of-month/day-of-week behaviour, and time-zone configuration. Also confirm whether the platform prevents overlapping runs or starts a new invocation regardless of the previous run's state.
How to interpret changes
When a scheduled job behaves unexpectedly, separate schedule problems from execution problems. Start by comparing the expected next run times with the scheduler's recorded invocation times.
- No invocation occurred: inspect whether the job is enabled, whether the expression parses, and whether the scheduler uses a different time zone.
- The job ran at the wrong time: check UTC versus local time, daylight-saving rules, server clock synchronisation, and whether the platform includes a seconds field.
- It ran on unexpected dates: examine the interaction between day-of-month and day-of-week fields. Implementations do not all interpret both fields in the same way.
- It ran twice: look for duplicate registrations, multiple scheduler instances, retries, overlapping windows, or a second platform also invoking the same command.
- It ran but produced no result: inspect exit codes, environment variables, permissions, working directories, input availability, and downstream service responses.
- It missed a run during a time change: determine how the scheduler handles nonexistent or repeated local times. For important jobs, a UTC schedule or an explicit time-zone-aware scheduler may be easier to reason about.
Retries need their own design. Retrying a read-only report may be harmless; retrying a payment, email, data export, or queue consumer can create duplicates. Use an idempotency key, a lock, a completion marker, or another application-level safeguard where repeated execution has side effects. A scheduler can trigger a command, but the command remains responsible for safe behaviour.
For an audit, compare three data points: the intended schedule, the scheduler's invocation record, and the application's completion record. This distinction helps identify jobs that start on time but fail, hang, overlap, or finish after their useful processing window.
When to revisit
Revisit every cron job when its business requirement, command, infrastructure, data window, owner, or hosting platform changes. A quarterly review is a practical baseline for important automation, with a shorter review cycle for jobs that affect customer communications, financial workflows, production data, or time-sensitive reporting.
Use this scheduled-job audit template:
- Job name and owner: Who maintains it and who responds to failure?
- Purpose: What outcome does the job produce?
- Expression and platform: What syntax is used, and where is it configured?
- Time zone: Is it explicit, and is the choice still correct?
- Expected run window: When should it start and finish?
- Overlap policy: Can another run begin before completion?
- Missed-run policy: Should a delayed task be skipped, caught up, or run manually?
- Retry and idempotency: What happens after a timeout or partial failure?
- Logging and alerting: Where are logs stored, and what event generates an alert?
- Last verification: When were upcoming dates and edge cases last tested?
At each review, generate future occurrences, test one successful execution and one controlled failure, inspect alert delivery, and remove obsolete schedules. If you migrate between platforms, keep the old and new schedules from running at the same time unless duplicate execution is explicitly safe. Finally, update the expression's comment or runbook with a plain-language description, owner, time zone, and expected behaviour. That small amount of documentation makes the next cron job troubleshooting session considerably faster.