Cron Expressions Explained: Syntax, Gotchas, and Production-Grade Schedules

Cron Expressions Explained: Syntax, Gotchas, and Production-Grade Schedules

Cron is fifty years old and still schedules most of the world's recurring work — backups, report generation, certificate renewals, cache warming, that one cleanup script nobody remembers writing. The syntax takes ten minutes to learn. What takes longer is discovering, one incident at a time, the behaviors nobody mentioned: the job that ran 56 times a year instead of 2, the backup that silently stopped when it moved to a container, the 2:30 AM task that vanished one Sunday in March.

This is the ten-minute syntax lesson plus the incidents, so you can skip having them.

The five fields

A cron expression is five space-separated fields, left to right from smallest unit to largest:

┌───────────── minute        (0–59)
│ ┌─────────── hour          (0–23)
│ │ ┌───────── day of month  (1–31)
│ │ │ ┌─────── month         (1–12, or JAN–DEC)
│ │ │ │ ┌───── day of week   (0–7; 0 and 7 are both Sunday, or SUN–SAT)
│ │ │ │ │
*  *  *  *  *   command to run

Each field takes:

Read right-to-left for the plain-English version: 30 3 * * 1 → Mondays (1), any month, any day-of-month, at 03:30. When an expression matters — meaning someone gets paged if you misread it — don't trust your own parsing. Our cron parser renders any expression as plain English with the next run times, which catches transposed fields instantly. (Everyone eventually writes 3 30 * * * for 30 3 * * *. That one asks for hour 30, which doesn't exist, so it never fires at all.)

The schedules you'll actually write:

Most crons also accept shorthands: @hourly, @daily, @weekly, @monthly, @yearly, and the odd one out, @reboot, which runs once at daemon startup — handy for "start my tunnel when the box boots," with the caveat that it also fires when merely the cron service restarts on some systems.

The special characters, one at a time

Two things the table above doesn't tell you. Ranges are inclusive at both ends, so 0 9-17 * * * gives nine runs, not eight. And a step is anchored to the field's range, not to the current time — */40 * * * * fires at :00 and :40 and then wraps back to :00, a 20-minute gap once an hour rather than "every 40 minutes". Only divisors of 60 behave the way the phrase "every N minutes" implies.

Three further characters turn up in cloud consoles and Java configs, and standard Linux cron rejects all of them. They come from Quartz; AWS EventBridge inherited them.

L means "last" — the last day of the month in day-of-month, and the last such weekday of the month in day-of-week:

0 0 L * ?     # midnight on the 31st in January, the 28th or 29th in February
0 22 ? * 5L   # 22:00 on the last Friday of every month

W means "nearest weekday" to a given day-of-month, and never crosses a month boundary. 15W fires on the 15th when that's Mon–Fri; a Saturday 15th moves back to Friday the 14th, a Sunday 15th forward to Monday the 16th. LW is the last weekday of the month.

0 9 15W * ?   # payroll: 09:00 on the nearest weekday to the 15th

# means "the Nth of that weekday in the month".

0 14 ? * 6#3  # 14:00 on the third Friday of every month

Look closely at that 6. Quartz and EventBridge number the week 1–7 starting at Sunday, so Friday is 6 — one higher than standard cron, where Friday is 5. Nothing errors; the job just runs a day late, every week, until someone notices. Write FRI#3 and the problem evaporates.

? means "I'm not constraining this field", and it exists only in the two day fields. Quartz-family schedulers refuse to guess how those fields combine, so they make you blank one out — which is why every example above has one. Standard cron doesn't force the choice, and that turns out to be a problem.

Installing your first crontab

Expressions live in a crontab — a plain text file, one job per line, owned by a specific user. You don't edit it directly; you go through the crontab command, so the daemon hears about the change. Open yours with crontab -e.

The first time you run that on a machine, two things happen that look like errors and aren't. First, the editor picker:

Select an editor.  To change later, run 'select-editor'.
  1. /bin/nano        <---- easiest
  2. /usr/bin/vim.basic
  3. /usr/bin/vim.tiny
  4. /bin/ed
Choose 1-4 [1]:

Press Enter for nano unless you have opinions. Second, above the file contents:

no crontab for alice - using an empty one

That's cron creating your crontab, not refusing to. Add a line at the bottom — this one writes a timestamp every minute, so you get feedback fast:

* * * * * /bin/date >> /tmp/cron-test.log 2>&1

Save and exit (in nano: Ctrl+O, Enter, Ctrl+X). Cron confirms with exactly one line:

crontab: installing new crontab

If you don't see that line, your job is not installed. A syntax error produces errors in crontab file, can't install and offers to re-edit — take the offer, or your edits are discarded. Then confirm what's loaded and, a couple of minutes later, that it ran:

crontab -l
cat /tmp/cron-test.log

Two or three timestamps, one per minute, means the whole chain works: daemon running, expression valid, command found, output landing where you told it. Establish that baseline before you debug a real job — it separates "cron is broken" from "my script is broken".

Two warnings. crontab -r deletes your entire crontab with no confirmation prompt, and it sits one keypress from -e — run crontab -l > ~/crontab.bak before editing. And crontabs are per-user: sudo crontab -u www-data -l is a different file from yours, which is why so many "it isn't running" jobs turn out to be installed under the wrong account.

System crontabs are the exception. Files in /etc/cron.d/ and /etc/crontab are edited with a normal editor and carry a username between the schedule and the command:

# /etc/cron.d/backup — note the extra 'root' column
30 3 * * *  root  /usr/local/bin/backup.sh >> /var/log/backup.log 2>&1

Omit it and cron rejects the line. And a Debian-ism worth knowing: filenames in /etc/cron.d/ may contain only letters, digits, underscores and hyphens. Call it backup.sh and the file is ignored entirely, without a word of complaint.

The OR trap: day-of-month vs. day-of-week

Here's the rule that catches everyone exactly once. You want a job on Friday the 13th, so you write:

0 0 13 * 5    # midnight, 13th of the month, Friday... right?

Wrong — that runs on every 13th and every Friday. When both day fields are restricted (neither is *), POSIX cron combines them with OR, not AND. It's documented, it's ancient, and it still produces ~56 runs a year where someone expected 2. If a report "randomly" arrives on days it shouldn't, check this before anything else. Three cases, and that's the whole rule:

The workaround: keep one field in cron, check the other in the command. Leave day-of-week as * so cron only handles the 13th, then let the shell throw away any 13th that isn't a Friday:

0 0 13 * *   [ "$(date +\%u)" = 5 ] && /path/to/friday13-job

date +%u prints the ISO day of week, 1 for Monday through 7 for Sunday, so 5 is Friday. Note the backslash before the %: inside a crontab a bare percent sign isn't a percent sign, it's a newline.

This is exactly the ambiguity ? was invented to kill — Quartz makes you blank one day field, so there's nothing left to combine. Which brings us to the dialect problem.

Every platform speaks a slightly different cron

Copy-pasting an expression between systems without checking the dialect is a classic way to be wrong quietly:

• AWS EventBridge uses six fields — it appends a year — requires ? in one day field, supports L and W, and evaluates in UTC unless configured otherwise. Standard five-field expressions are rejected or reinterpreted.
• GitHub Actions uses standard five fields but is UTC-only, has a floor of 5 minutes, and treats the schedule as best effort. High-load periods (the top of every hour especially) routinely delay workflows by many minutes, and runs can be skipped entirely. Never put anything time-sensitive on it — and note that scheduled workflows on repos idle for 60 days get disabled automatically.
• Kubernetes CronJob uses standard five fields, defaults to the controller's timezone, and since v1.27 supports an explicit timeZone: "Etc/UTC" field — set it, always. startingDeadlineSeconds and concurrencyPolicy: Forbid are Kubernetes' answers to missed runs and overlap.
• Quartz (Java land) uses six or seven fields starting with seconds, so a copied five-field expression shifts every value one position left. It fails loudly, at least.
• systemd timers aren't cron at all. They use their own calendar syntax (OnCalendar=Mon..Fri 03:00) and their own semantics, so there's nothing to port — you rewrite the schedule.

The five-field expression is the lingua franca; just confirm what accent the destination speaks before deploying.

Why your job runs in your terminal but not in cron

The number-one cron question online isn't about syntax at all — it's "my job doesn't run." Ninety percent of the time it's one of these four, in this order:

1. The environment isn't your environment. Cron launches commands with a nearly empty environment: PATH is typically /usr/bin:/bin, SHELL is /bin/sh (not bash), and none of your .bashrc or .profile setup exists. So node script.js works at your prompt and produces node: command not found in cron — except you never see that message (see #3). Anything installed by nvm, pyenv, rbenv, asdf or Homebrew is invisible here, because all of those work by editing your shell profile, and cron doesn't read shell profiles.

Two fixes, and you want both: absolute paths for the interpreter and the script, plus an explicit environment declared above the job lines.

PATH=/usr/local/bin:/usr/bin:/bin
SHELL=/bin/bash
MAILTO=""

30 3 * * *  /usr/local/bin/node /srv/app/scripts/report.js >> /var/log/report.log 2>&1

Those assignments are crontab syntax, not shell syntax — no export, no quotes — and they apply to every line below them. MAILTO="" turns off cron's mail attempts, which is what you want once output goes to files. Get the absolute path for anything you're unsure of with command -v node.

2. The percent sign. An unescaped % is a newline, and everything after it becomes stdin to the command — so date +%Y-%m-%d breaks in a genuinely baffling way. Escape it: date +\%Y-\%m-\%d.

3. Output goes nowhere you look. Cron mails stdout and stderr to the user's local mailbox, which on a modern server is a file nobody has opened since the box was provisioned. Until you append >> /var/log/myjob.log 2>&1, every failure is invisible. First thing to add when debugging, not the last.

4. Crontab formalities. Wrong user, missing sixth column — both look exactly like "the job isn't running". And some implementations still ignore a crontab's final line if the file lacks a trailing newline. Yes, still. End the file with a blank line and stop thinking about it.

Debugging a cron job that isn't running

When a job doesn't fire, resist the urge to change the expression. Work the chain in order: is it installed, is the daemon alive, did cron try, and did the command survive cron's environment.

Step 1 — confirm it's installed, under the right user. From any shell:

crontab -l                    # your own jobs
sudo crontab -u www-data -l   # a service account's jobs
cat /etc/crontab; ls /etc/cron.d/   # system jobs, which crontab -l never shows

If your line isn't in that output, nothing else matters — wrong user, or the install silently failed.

Step 2 — confirm the daemon is running. The unit name differs by distro, which is its own half-hour of confusion:

systemctl status cron     # Debian, Ubuntu
systemctl status crond    # RHEL, Rocky, Fedora, Amazon Linux

You want Active: active (running). In a container, there's a good chance no cron daemon was ever started at all — that's the usual reason a crontab that worked on a VM does nothing after a Dockerfile port.

Step 3 — ask cron whether it tried. People skip this one, and it's the step that splits the problem in half:

grep CRON /var/log/syslog                    # Debian/Ubuntu with rsyslog
journalctl -u cron --since "1 hour ago"      # systemd journal; crond on RHEL

-u filters to one unit, --since takes plain English like "today". An attempt looks like this:

Jul 20 03:00:01 web01 CRON[24192]: (deploy) CMD (/usr/local/bin/backup.sh)

If that line is there, cron did its job and your script is the problem. If it isn't, cron never fired — bad expression, wrong user, dead daemon, rejected line. Two more lines worth recognizing:

Jul 20 03:00:01 web01 CRON[24192]: (CRON) info (No MTA installed, discarding output)
Jul 20 03:00:01 web01 CRON[24191]: (CRON) error (grandchild #24192 failed with exit status 127)

The first is cron admitting it destroyed your evidence. The second is the one you're hunting — exit status 127 is the shell's code for "command not found", the PATH problem confessed in numeric form.

Step 4 — reproduce cron's environment at your prompt. env -i runs a command with a completely empty environment, so this is as close to being cron as you get without waiting for the next tick:

env -i PATH=/usr/bin:/bin HOME="$HOME" SHELL=/bin/sh \
  /bin/sh -c '/usr/local/bin/backup.sh'

Works in your shell, dies here? You've reproduced the bug in one second instead of one night. To capture the exact environment your daemon hands your jobs, drop in a one-minute probe — * * * * * env > /tmp/cron-env.txt 2>&1 — then read the file and delete the line.

Correlating a cron run against an application log always ends in epoch seconds; the epoch converter translates both directions, and the date calculator handles "how long between these two runs" without off-by-one surprises.

The DST incidents

Cron matches against local wall-clock time, and twice a year the wall clock misbehaves. On spring-forward night, 02:00 jumps to 03:00 — a job scheduled at 2:30 has no 2:30 to run in. On fall-back night, 01:00–02:00 occurs twice.

The mainstream Linux cron (Vixie/ISC) has thought about this: after a spring-forward jump it runs the skipped jobs once shortly after the change, and after fall-back it avoids running the repeated window twice. The bad news is that this is implementation-specific — a slim container image, a NAS, or a cloud scheduler may just skip or double-run — and even on mainline Linux, a "runs shortly after" backup that assumed a quiet 2:30 AM now executes during whatever else is happening at 3:01.

Two policies make the whole problem disappear:

• Run hosts and containers in UTC. UTC has no DST, so wall clock and schedule agree year-round. When a job must align to a local business hour, convert explicitly — the timezone comparison tool shows the UTC hour for any local time, including how it shifts across DST boundaries.
• If local time is unavoidable, schedule outside 01:00–03:00. A 3:30 AM job is exactly as quiet as a 2:30 one, and it exists on all 365 days.

Both rest on the same idea — keep an offset-free clock underneath, convert at the edges — which is the whole argument of our guide to Unix timestamps, timezones, and DST. If your job writes times into a database, read that one before you pick a column type; it covers why a fall-back timestamp maps to two real instants. For a quick conversion mid-incident, the Unix timestamp converter does the back-and-forth in the browser.

Overlap: the failure mode that compounds

Cron schedules starts. It doesn't know or care whether the previous run finished. The incident pattern is always the same: a nightly job's runtime creeps up as data grows, one night it exceeds 24 hours, the next start piles on, both run slower, and within a week several copies are deadlocking each other and the database. The "harmless" cleanup script becomes the outage.

Here's what it looks like caught in the act — a sync job on a */10 schedule, inspected at 02:47:

ps aux | grep '[s]ync-job'

USER    PID   %CPU %MEM    RSS STAT START   TIME COMMAND
deploy 14203  62.1  8.4 689104 D    02:00   0:29 /usr/bin/python3 /usr/local/bin/sync-job
deploy 15044  58.7  8.3 683992 D    02:10   0:24 /usr/bin/python3 /usr/local/bin/sync-job
deploy 15991  55.2  8.4 690440 D    02:20   0:21 /usr/bin/python3 /usr/local/bin/sync-job
deploy 16702  51.9  8.3 684180 D    02:30   0:18 /usr/bin/python3 /usr/local/bin/sync-job
deploy 17455  48.3  8.4 689960 D    02:40   0:15 /usr/bin/python3 /usr/local/bin/sync-job

The START column is the whole story: five processes, exactly ten minutes apart, none exited. STAT of D is uninterruptible sleep — they're blocked on I/O, almost certainly on each other's database locks. RSS at ~690 MB apiece makes 3.4 GB nobody planned for. Another four hours and the box either OOM-kills something important or stops answering SSH. (The bracket in grep '[s]ync-job' keeps grep out of its own results.)

The one-line insurance is flock:

*/10 * * * *  flock -n /tmp/sync.lock /usr/local/bin/sync-job >> /var/log/sync.log 2>&1

flock takes a lock file and a command: it grabs an exclusive lock, runs the command, and releases the lock when the command exits — including when it crashes, since the kernel drops the lock with the file descriptor. -n ("nonblocking") makes a second instance give up immediately rather than queue, which is right for periodic work: the next tick picks it up. One quirk to know before you test it: a blocked flock -n exits 1 and prints nothing at all — it fails silently by default, which is exactly what you want in a crontab and exactly what confuses everyone the first time.

Two honest limits. flock is per-machine: the same entry on three app servers gives you three concurrent jobs, since they lock three different files on three different filesystems. Fleet-wide exclusion needs a distributed lock (Redis SET NX with a TTL, a database advisory lock) or a scheduler pinned to one node. And flock never tells you it skipped — a job that quietly declines to run for a week looks exactly like a healthy one. Which is the deeper problem.

Silent success is indistinguishable from silent failure

The most dangerous cron job is one that has been "working" for two years — meaning: nobody has checked. Logs answer what happened; they don't alert you that nothing happened, which is the failure mode of a stopped daemon, a typoed crontab, or a disabled GitHub Actions schedule.

The pattern that catches everything is the dead-man's switch: the job's last action is pinging a heartbeat URL, and the monitor alerts when the ping doesn't arrive on schedule. Point it at a URL you watch — even a webhook tester endpoint works for verifying the mechanism before you wire up a real monitor:

0 3 * * *  /usr/local/bin/backup.sh && curl -fsS https://your-heartbeat-url/backup-ok >> /var/log/backup.log 2>&1

Note the && — the ping only fires on success, so both "job failed" and "job never ran" produce the same alert. Then test it once by breaking the job on purpose. An alert that has never fired is a hypothesis.

When to graduate from cron

Cron is the right tool for single-machine, time-triggered, fire-and-forget work. Three signals you've outgrown it:

1. You need missed runs to catch up — the server was down at 3 AM and the backup should still happen. systemd timers do this with one line, Persistent=true; cron just skips it.
2. You need sub-minute precision or guaranteed timing. Cron's floor is one minute and its guarantee is "roughly then."
3. You need retries, visibility, or distribution — one job across many workers, dashboards, failure handling. That's a queue or a workflow engine, not a scheduler.

"One line" is cheap without the other lines, so for scale: a timer is two files sharing a basename — backup.service does the work, backup.timer says when — in /etc/systemd/system/, plus a daemon-reload and an enable --now. The schedule half is short:

[Timer]
OnCalendar=*-*-* 03:30:00
Persistent=true
RandomizedDelaySec=300

[Install]
WantedBy=timers.target

OnCalendar is systemd's syntax, not cron's — *-*-* 03:30:00 is year-month-day then time; Mon..Fri 09:00 does weekdays. The payoff for that boilerplate is systemctl list-timers, which tells you when a job runs next and when it last ran — a question cron has never been able to answer — plus exit codes in systemctl status and output in journalctl -u backup.service, captured with no redirect to remember.

Past that tier, once jobs need retries, branching, external triggers, and a record of what ran and why, you want a workflow engine rather than a scheduler; our n8n setup guide covers self-hosting one.

The graduation path is normal: crontab entry → systemd timer → queue. The mistake is only in skipping the middle upgrades after the reliability requirements have arrived.

The gotcha checklist

Every one of these has caused a real incident. Read it before you deploy a schedule, and again when one misbehaves.

1. The two day fields OR together. 0 0 13 * 5 is the 13th or Friday — ~56 runs a year.
2. Steps anchor to the field's range, not to now. */40 gives :00, :40, then a 20-minute gap.
3. Cron's PATH is /usr/bin:/bin, and no shell profile loads. Anything from nvm, pyenv, asdf or Homebrew is invisible.
4. A bare % is a newline. Escape every one as \%, especially inside date +....
5. Without >> logfile 2>&1, output goes to a mailbox nobody reads — or nowhere, if no MTA is installed.
6. /etc/cron.d/ and /etc/crontab need a sixth column (the user), and filenames there can't contain dots.
7. Jobs are per-user. crontab -l says nothing about www-data's jobs.
8. Cron uses the system timezone, and containers are almost always UTC.
9. Don't schedule between 01:00 and 03:00 local. Spring-forward deletes that hour; fall-back repeats it.
10. Cron schedules starts, not completions. Wrap it in flock -n — and remember the lock is per-machine.
11. crontab -r deletes everything with no prompt. Back up first.
12. A job that has "worked for years" is a job nobody has checked. Heartbeat it, then break it on purpose.
13. Dialects differ. EventBridge takes six fields and numbers Friday as 6; Quartz starts at seconds; GitHub Actions is UTC-only and best-effort.

The short version

Five fields, smallest to largest; verify expressions with a parser instead of your eyeballs; remember day-of-month and day-of-week OR together; give every production job absolute paths, redirected output, a flock, and a heartbeat; keep servers on UTC; and treat "it's been working for years" as a reason to check, not a reason not to.