Koha's web interface shows you the library. The cron jobs are what make it behave over time.
This distinction matters because of how these fail. Miss a scheduled job and nothing errors. No warning appears, no screen turns red. A number is simply always zero — and you find out months later when someone asks why no patron has ever been charged a fine.
The essential cron jobs
| Job | What it does | Frequency | What silently breaks without it |
|---|---|---|---|
| Fines | Accrues overdue charges | Daily | Nobody is ever fined. No error; balances stay zero |
| Overdue notices | Generates overdue messages | Daily | No overdue reminders. Patrons keep items indefinitely |
| Message queue | Sends queued email | Every 15–60 min | Notices generate and never send. Queue grows forever |
| Holds queue | Builds the pull list | Several times daily | Staff have no list of holds to fetch from the shelves |
| Expired holds | Cancels holds not collected | Daily | Uncollected holds block items for the next patron indefinitely |
| Automatic renewals | Renews eligible loans | Daily | Auto-renew is advertised to patrons and never happens |
| Long overdue | Marks very late items lost, charges replacement | Daily | Items stay "overdue" forever; stock figures wrong |
| Session cleanup | Clears expired sessions | Daily | Database grows; logins slow over months |
| Search index | Keeps the index current | Continuous or frequent | New records are invisible in search |
The "silently breaks" column is the one to read twice. Every entry is a failure with no error message.
Fines and overdues
The two most consequential, and the most commonly missing.
Order matters: fines should accrue before overdue notices generate, so a notice states the correct amount. Reversed, patrons receive notices quoting yesterday's balance and dispute the difference at the desk.
If fines are not appearing at all, check this job before anything else. It is the answer more often than any configuration setting.
The message queue
Generating a notice and sending it are two different jobs, and this catches people constantly. Koha writes notices into a queue; a separate job delivers what is waiting.
You can therefore have a perfectly configured mail server, correct templates, working triggers — and no email, because nothing is processing the queue. See Koha overdue notices not sending for the full diagnostic path.
Holds and the holds queue
The holds queue job builds the list staff use to pull requested items off the shelves. Without it there is no list, holds sit unfulfilled, and patrons who placed a hold on an available item are told nothing.
The expired-holds job matters just as much in the other direction: without it, an uncollected hold blocks that copy for everyone else, permanently.
Automatic renewals
Worth verifying against your circulation rules before switching on. Auto-renewal interacts with hold status, renewal limits and patron account expiry, and the combination occasionally surprises people. Test with a real loan before announcing it.
Housekeeping
Session cleanup, temporary file removal and index maintenance degrade slowly rather than failing outright. Nobody notices for a year, and then the system is inexplicably sluggish.
How to tell whether a job actually ran
The hard part, and the reason this article exists.
- Check the crontab for the instance user, not root. Jobs added to the wrong user's crontab are a classic failure — they exist, they just never run as anyone who can do anything.
- Redirect output somewhere. A job whose output goes nowhere cannot be diagnosed after the fact.
- Look for effects, not evidence of execution. Did any fine accrue yesterday? Did any notice enter the queue? These are the real tests.
- "No error email arrived" proves nothing. A job that was never scheduled sends no errors either. This is the reasoning trap that keeps libraries confident and wrong.
The underlying problem is that Koha gives you no readable history of what ran and what it did. You are inferring backwards from effects — which works, but only once you already suspect something is wrong.
That is worth fixing at the platform level rather than per library. On Koha Cloud these jobs are managed and each library gets a readable run history, so "did fines accrue last night?" is a question you answer by looking rather than by trusting. Scheduled jobs you can actually see — no SSH, no crontab.
Common cron mistakes
- Wrong user — added to root instead of the Koha instance user.
- Missing environment — cron runs with a minimal environment; a script that works in your shell may not work in cron.
- Overlapping runs — a long job still running when the next starts. With fines, this can double-charge.
- Output discarded — nothing to look at when it goes wrong.
- Lost in a server migration — the database and files were moved, the crontab was not. Everything looks fine for weeks.
- Removed during an upgrade and never restored. See our upgrade guide.
A monthly verification routine
- Did any fine accrue in the last week?
- Did any overdue notice enter the queue?
- Is the queue draining, or growing?
- Does the holds pull list have today's date?
- Have any long-overdue items been marked lost recently?
- Do newly cataloged records appear in a search?
Six questions, five minutes, once a month. It catches almost everything on this page before a patron does.
Suspect a job has not run in months? We audit Koha scheduled jobs and tell you exactly what has and has not been happening — usually within a day.