Background Job Workers instead of Cron?

RTechSn · January 28, 2026, 1:37pm

I have no support/technical question and have seen the support category. (Be aware that direct support questions will be deleted.)

on

Which general topic do you have

Hello.
I’ve found an interesting feature on Nextcloud: occ background-job:worker.
There were some stuck jobs on my server and this tool has really helped me out.
I’ve been using systemd timer, and crontab before that, but after updating to the latest version a week ago background jobs weren’t running. I suspect the Passwords app is the culprit.
Anyway, the problem is resolved after running the worker. But I’ve decided to leave it running for a while and was surprised by how fast the notifications started to arrive. It would take around 15-30 seconds before, but it’s almost instant with the worker.

I’ve asked an LLM to make me a systemd unit and this is what it has come up with:

/etc/systemd/system/nextcloud-worker@.service

[Service]
User=www-data
Group=www-data
ExecStart=/usr/bin/php /var/www/nextcloud/occ background-job:worker

# 1. ALWAYS RESTART
Restart=always

# 2. WAIT 5 SECONDS
# Prevents the worker from respawning instantly and crashing again
# (which would lock up the CPU before you could intervene).
RestartSec=5s

# 3. PREVENT RESTART SPAM (Crash Protection)
# If the worker crashes more than 5 times in 60 seconds,
# systemd will stop trying to restart it for a while.
StartLimitIntervalSec=60
StartLimitBurst=5

#Added later after reading the documentation
#Kills the worker every N seconds to pick up new settings.
RuntimeMaxSec=3600

# Low priority
Nice=19
IOSchedulingClass=idle
PrivateTmp=yes

sudo systemctl enable --now nextcloud-worker@1
sudo systemctl enable --now nextcloud-worker@2

I would like to ask dear developers of Nextcloud:

Do you approve this method of running background jobs, or there may be some caveats?
Is it allowed to run multiple parallel workers?

tflidd · January 29, 2026, 9:38am

I didn’t find anything in the documentation. However, you can track down and find a few things on github, here the feature was introduced:
https://github.com/nextcloud/server/pull/30359
Feature request for a runner:

github.com/nextcloud/server

RFC: Implement a runner for fast background jobs

opened 09:23AM - 05 May 25 UTC

marcelklehr

enhancement 0. Needs triage

### How to use GitHub * Please use the 👍 [reaction](https://blog.github.com/201…6-03-10-add-reactions-to-pull-requests-issues-and-comments/) to show that you are interested into the same feature. * Please don't comment if you have no relevant information to add. It's just extra noise for everyone subscribed to this issue. * Subscribe to receive notifications on status change and new comments. **Is your feature request related to a problem? Please describe.** Currently, some apps require the setup of a fast background job worker using `occ background-job:worker`. Some apps require more than one worker of the same job, even. Setting these up e.g. with systemd is cumbersome and repetitive. Additionally for nextcloud AIO, it would be beneficial to have a generic way to run these without hard coding jobs for all possible apps in the AIO code. **Describe the solution you'd like** We could have a new php script next to cron.php and occ or just another occ command that * figures out which jobs to run * runs the necessary background workers as sub processes * keeps track of them and restarts them when they fail or exit * Passes the stdout of the workers through to its own stdout Background services could be set via a a php file, or a json file. A service could be either a `background-job:worker` `"worker"` or a `"dedicated-cron"` `cron.php` runner, with a set list of jobs. This would cater to both `QueuedJob`s and `TimedJob`s (the latter cannot be run by the bg-job worker). ```json { "services": { "TaskProcessing 1": { "type": "worker", "jobs": ["OC\\TaskProcessing\\SynchronousBackgroundJob"], }, "TaskProcessing 2": { "type": "worker", "jobs": ["OC\\TaskProcessing\\SynchronousBackgroundJob"], }, "WebhookListeners": { "type": "worker", "jobs": ["OCA\\WebhookListeners\\BackgroundJobs\\WebhookCall"], }, "ContextChat": { "type": "dedicated-cron" "jobs": ["OCA\\ContextChat\\BackgroundJobs\\CrawlJob", "OCA\\ContextChat\\BackgroundJobs\\IndexerJob"], } } } ``` Services would be started only if the respective job classes are loadable in the main php process. **Describe alternatives you've considered** We could also leave out the dedicated cron feature, which would make the whole thing less powerful but still useful. **Additional context** -

On the forum, just an unanswered help request:

If you have broken background jobs, you should also find out which ones are failing and repair them (or report a bug). The oc_jobs table should help you which jobs run when for the last time and how long it took, and of course when it is running the logfiles (and you might have some errors when you call the jobs directly from command line).

jtr · January 30, 2026, 3:40am

Probably needs a general write-up in the Background Jobs section of the Admin Manual (any volunteers?), but there are two spots in the manual where worker mode is documented (because the worker is more often used with these features):

RTechSn · January 30, 2026, 12:38pm

Thank you, I no longer have them. Either running the worker, or occ maintenance:repair has fixed this stuckness.
I suspect the Passwords app was the problem, it keeps spamming “Failed to update all target passwords in 32 loops, 1 still pending update” in my log even after the job issue was resolved.
I’ve found an exising issue [BUG]: Loop 'Failed to update all target passwords in 32 loops, 57 still pending update' · Issue #739 · marius-wieschollek/passwords · GitHub
so I guess it’s not a problem with my particular instance.

This answers both my questions, thanks!