Configuration & operations
Koha background jobs stay at "New" and never finish
A staged MARC import or batch modification that sits at "New" means no worker is taking jobs from that queue. Start the worker for both queues and the jobs run.
By Babar Junaid
Published 2026-11-09 · Tested against Koha 26.05
A job that stays at New under Administration → Jobs has been queued, but no worker is reading its queue. Koha 22.11 and later run staged MARC imports, batch item and record changes and batch deletions in a separate koha-worker process. Run sudo koha-worker --all-queues --start library and the waiting jobs start within seconds.
Step 1: See which workers are running
Koha has two queues, and each has its own worker. default takes the short jobs; long_tasks takes the slow ones, which include staging and importing MARC records and batch item modification.
$ sudo koha-worker --status --all-queues library * worker running for library (default) [ OK ] * worker not running for library (long_tasks) [fail]Response from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server
Replace library with your instance name (sudo koha-list prints it). Each line ends in [ OK ] or [fail]. In a script or a cron email, where there is no terminal, the same lines read worker running for library (default):. and worker not running for library (long_tasks): failed!. What matters is running or not running for each queue. The example above is the commonest broken state: somebody started the worker by hand without --all-queues, so it took only default. Short jobs work and every import waits forever.
Step 2: Start both queues
$ sudo koha-worker --all-queues --start libraryError: worker already running for library (default)Starting Koha worker daemon for library (long_tasks) ...fail!$ sudo koha-worker --status --all-queues library * worker running for library (default) [ OK ] * worker running for library (long_tasks) [ OK ]Response from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server
Ignore the ...fail!. The script counts the queue that was already running as an error, so it reports failure even though long_tasks has just started. Wait a few seconds and run --status again: both queues should say running and [ OK ]. Then reload Administration → Jobs: the jobs that were waiting move to Started and then Finished. Nothing needs to be submitted again.
Make it survive a reboot
sudo systemctl is-enabled koha-common answers enabled rather than starting workers by hand each time.Step 3: If the worker starts and the jobs still do not run
The worker restarts itself when it crashes, so a worker that dies on every job looks like a worker that is running. Its errors go to their own log, not to the intranet log:
$ sudo tail -n 50 /var/log/koha/library/worker-error.log…20261108 05:41:31 library-koha-worker: client (pid 12299) killed by signal 15, respawning20261108 05:41:31 library-koha-worker-long_tasks: client (pid 12306) killed by signal 15, respawning20261108 05:46:14 library-koha-worker-long_tasks: client (pid 400) killed by signal 15, stoppingResponse from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server
Lines like these are normal: killed by signal 15, respawning is a restart, stopping a stop. A Perl error between them (a missing module after an upgrade, a database permission) is the real problem, and the jobs will run once it is fixed. An empty log with jobs still at New points at the message broker, below.
Step 4: Check the message broker (RabbitMQ)
By default Koha hands jobs to the worker through RabbitMQ, using the STOMP protocol on port 61613. Open More → About Koha → System information. If you see Impossible to connect to the message broker, or the server information shows Using SQL polling (Fallback, Error connecting to RabbitMQ), the broker is not reachable.
$ sudo systemctl status rabbitmq-server● rabbitmq-server.service - RabbitMQ Messaging Server Loaded: loaded (/usr/lib/systemd/system/rabbitmq-server.service; enabled; preset: enabled) Active: active (running) since ……$ sudo rabbitmq-plugins enable rabbitmq_stompEnabling plugins on node rabbit@koha-server:rabbitmq_stompThe following plugins have been configured: rabbitmq_stompApplying plugin configuration to rabbit@koha-server...Plugin configuration unchanged.$ sudo systemctl restart rabbitmq-serverResponse from a run on a fresh Ubuntu 24.04 server
Active: active (running) is what you want. Plugin configuration unchanged. means STOMP was already on; a missing plugin prints The following plugins have been enabled: instead. The node name after rabbit@ is your server's hostname. The restart prints nothing. Then restart the workers so they connect again:
$ sudo koha-worker --all-queues --restart libraryRestarting Koha worker daemon for library (default)Restarting Koha worker daemon for library (long_tasks) ...done.Response from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server
The Koha package enables the rabbitmq_stomp plugin when it installs, so a missing plugin usually means RabbitMQ was reinstalled or upgraded afterwards. A worker that cannot reach the broker when it starts falls back to checking the database every 10 seconds, so a broker that is down for good only makes jobs slow.
Jobs submitted while RabbitMQ was down
A broker that was down for a while and came back is worse. A job submitted in that window is saved with status New but never handed to RabbitMQ, and a worker connected to RabbitMQ only takes jobs from RabbitMQ: it never looks in the database. Those jobs stay at New for good, with both workers running. We reproduced it on a Koha 26.05 server: two jobs queued with RabbitMQ stopped were still New after RabbitMQ and the workers were restarted.
To run them, make the worker read the database once. Set Administration → System preferences → JobsNotificationMethod to polling, then restart the workers:
$ sudo koha-worker --all-queues --restart libraryRestarting Koha worker daemon for library (default)Restarting Koha worker daemon for library (long_tasks) ...done.Response from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server
Within about ten seconds the waiting jobs move to Started and Finished. Then set the preference back to STOMP and restart the workers again, or leave it on polling (below). Change it on the preferences screen rather than in the database: Koha caches its preferences, and a direct UPDATE is not seen by the worker.
Running without RabbitMQ on purpose
JobsNotificationMethod system preference to polling. Jobs then start within about ten seconds, and About Koha stops warning.Why this happens
Before Koha 22.11 a staged import ran inside the web request that started it, which tied up the browser and timed out on large files. Now the screen only writes a row to the background_jobs table with status new and returns immediately. Every slow operation depends on a separate daemon picking that row up, and nothing on the screen tells you the daemon is missing.
The split into two queues is what makes the half-working state so common. koha-create and the boot service both start default and long_tasks. A worker started by hand, from an old guide or after a crash, gets default only. The short jobs prove the worker is alive, while every import waits in the queue nobody reads.
Troubleshooting
| What you see | Cause |
|---|---|
| Imports and batch modifications stay at New; small jobs finish | Only the default worker runs. Start long_tasks (step 2) |
| Every job stays at New | No worker at all, or the koha-common service is disabled |
| Jobs go to Started and then Failed | The job itself failed: open the job for its report, and read worker-error.log |
| Jobs start, but only after 10 seconds or more | RabbitMQ is unreachable and the worker is polling (step 4) |
| Both workers run, new jobs finish, but some older jobs stay at New | They were submitted while RabbitMQ was down and never reached it. Switch to polling once (step 4) |
| Import finished but the records are not in search | The search index is behind, not the job: see rebuilding the Zebra index |
If the job was a MARC import, importing MARC records into Koha walks through the staging screens that queue it. The scheduled jobs in Koha's cron jobs are separate from this worker and can be healthy while it is down.
Tested on live Koha 26.05.05
Passed all 20 checks · Read the run log
- Koha release
- 26.05.05
- System
- Ubuntu 24.04
- Setup
- A fresh Ubuntu 24.04 server reached over SSH as a sudo user, Koha installed from the Koha repository as our installation guide leaves it.
- Source read at
- Koha commit d3fc229
Earlier live checks (1)
- , Koha 26.05.02 (commit d3fc229): all 13 claims held. Read the run log
In the Koha manual (26.05)
Verified against the Koha source (7 files)
- debian/scripts/koha-worker (lines 41-95)
- debian/scripts/koha-functions.sh (lines 233-250)
- debian/koha-common.init (lines 66-68)
- misc/workers/background_jobs_worker.pl (lines 85-226)
- Koha/BackgroundJob.pm (lines 60-180)
- koha-tmpl/intranet-tmpl/prog/en/modules/admin/preferences/admin.pref (lines 195-200)
- koha-tmpl/intranet-tmpl/prog/en/modules/about.tt (lines 273, 535)
The label under each command says where its response came from; a command with no label was not run live. How we test and which standards we follow.
Jobs still sitting at "New"? Send us the output of koha-worker --status and we will get the queue moving on your server.
Want your staff trained on this? We teach it hands on with a live Koha, online or at your library. Ask about staff training
Related
More on configuration & operations
Answers to the questions that usually arrive with this one.
Koha independent branches: what IndependentBranches separates
IndependentBranches keeps staff to their own library's items, loans, holds and patron edits. It does not split the catalogue, and it does not hide other libraries' patrons: a permission does that. Tested both ways.
How to add a library (branch) in Koha
Adding a branch to Koha takes one form, but the code you choose is permanent and a new library needs a calendar, circulation rules and staff before it can lend. Here is the form, every field that matters, and what to set up next.
Koha search says "No results found" for everything
When every search in Koha finds nothing, the records are almost always fine and the search engine is not answering. Here is how to find which part stopped and bring it back, for Zebra and Elasticsearch.
How to edit notices and slips in Koha (templates and variables)
Every email, SMS and printed slip Koha sends comes from a template in Tools → Notices and slips. Here is how to edit one, add the patron’s name or the due date with a variable, give one library its own wording, and test it before it reaches a patron.

