Fixing ERPNext scheduled jobs that do not run

Why ERPNext scheduled jobs that do not run matter

A stopped scheduler is a day-two operations problem, and it rarely announces itself. Auto repeat invoices stop generating, scheduled reports stop arriving, and emails or backups quietly stop running, sometimes for days before anyone notices. In ERPNext, the scheduler decides which periodic jobs are due and hands them to background workers, which do the actual work. Job state is kept per site, so one site on a bench can fall behind while the others keep running normally. A failure can therefore look like a business problem (missing invoices, late reports) long before it looks like an infrastructure problem.

The failure has several possible causes, and each one sits in a different layer. The scheduler process may not be running, workers may be busy or missing a queue, or a specific site may have paused or stalled its own job state. The frappe_docker setup separates the scheduler into its own service next to the background workers, so a container can show as healthy while the scheduler inside it is idle. Before you plan any fix, confirm your version on the Frappe supported versions page. Version 14 reached end of life on January 31, 2026, version 15 is planned for support until the end of 2027, and version 16 until the end of 2029. The remaining support window decides how much effort a fix deserves.

Outside help is worth considering in three situations: your team has no internal Frappe skills, the same job failure keeps returning after each fix, or your version is close to end of life and an upgrade is already on the table. Ask any partner to start from the same evidence you would use internally: which jobs should have run, which ones did, and what the scheduler and worker logs show for the same window. A quote should name the sites, the bench setup (bare bench, Docker or Kubernetes), and whether the fix includes a documented runbook your team can repeat.

Which check fits which symptom

This table maps each symptom you see on a running ERPNext to the first check worth running and what its result tells you. Read it from the left column: find the symptom, run the listed check, then compare the result with the meaning in the last column. Exact command output and log wording vary by Frappe version, so confirm them against the version you run before relying on them.

Symptom	First check to run	What a result means
No scheduled jobs run on any site	bench doctor output on the bench host, checking the scheduler and worker process status	If the scheduler is reported as not running, the scheduler process or its supervisor service is down, not the sites themselves
One site's auto repeat has stopped	Scheduler status for that site, then the Scheduled Job Log filtered to that site	Scheduler enabled for the bench but paused or disabled on that site points to a site-level setting, not a host problem
Emails are queued but not sent	Pending job list for the default queue, then the Email Queue status in the desk	Queued jobs with no progress suggest workers are not consuming the queue, while a sent-failed status points to the mail account, covered in the email troubleshooting topic
Backups are missing from the expected folder or schedule	Scheduled Job Log entries for the backup job, with its last run time and status	No log entry means the job never ran, while a failed entry shows the error that stopped it
Jobs listed as pending for a long time	Pending job list with queue names and enqueue times	Long-pending jobs in a queue with no active worker mean the worker for that queue is missing or stalled, so check worker logs next
Jobs failing with errors	Scheduled Job Log entries and the worker log for the same time window	The log traceback names the failing function, which tells you whether the cause is code, data, a missing dependency or a timeout

Single site stalled or every site stalled

When only one site stops running scheduled work, the fault usually sits in that site's data, configuration or job definitions, because the scheduler and workers serving the other sites are still doing their jobs. Start from that site and work through its own records before touching shared services.

Site scheduler status: Check whether the scheduler is enabled for that site with bench --site <site> scheduler status. A disabled scheduler on one site explains jobs that never queue there.
Pending jobs for that site: Look at queued and failed jobs tied to the site. A backlog that keeps growing for one site often means the same job fails repeatedly on that site's data.
Scheduled Job Log: Filter the Scheduled Job Log to the site and look for repeated errors against one job type, such as Auto Repeat or email fetching.
Scheduled job types: Confirm that the affected job types are enabled and that their frequency matches what you expect. A disabled or altered job type is a common reason for silence.
Site-specific records: Auto Repeat documents with invalid dates, email accounts with broken credentials or a site left in maintenance mode can stop work for that site alone.

Before changing any setting, record the site name, the job type involved and the timestamp of the last successful run, since those details decide whether the fault is local.

When every site on a bench stops at the same time, suspect the shared layer: the scheduler process, Redis, the worker services or the bench itself. A single faulty site record rarely stops all sites at once, so begin with the processes that every site depends on.

Scheduler process: Confirm the scheduler service is running under your process manager and is not stuck or restarting in a loop. Read its logs for startup errors.
Redis and queues: Confirm the bench can reach Redis, because queued work and scheduler coordination depend on it. Connection errors show up across all sites together.
Worker services: Check that the worker processes for each queue are running. Workers that exit quietly leave every site's jobs pending.
Bench health output: Run bench doctor to get a health report covering services and background workers for the bench. Save its output before any restart so you can compare later.
Recent changes: Review upgrades, configuration edits and infrastructure changes made shortly before the stop, since one shared change can halt every site.

If the health output points to a service you do not operate directly, such as a managed Redis or a hosting platform's worker layer, confirm who owns that service before you restart anything.

Diagnosing a stopped scheduler with bench doctor and pending jobs

This sequence moves from version checks to the scheduler, queue and logs, so you can find which layer stopped and fix one cause with a test job. It gives your team a written record of what was broken and how it was confirmed.

Confirm Frappe and ERPNext versions
Record the installed Frappe Framework and ERPNext versions for the bench, then compare them with the supported versions page to confirm the release is still listed as supported. Ask your administrator to run the version check from the bench directory, using the command set in the documentation for the installed version. Done means you have both version numbers written down with the support status for each. If the release is end of life, note that before going further, because the fix may be an upgrade rather than a config change.
Run bench doctor and record findings
Run the bench doctor diagnostic from the bench directory and save its full output to a file before changing anything. It reports on background services and the scheduler, so note every warning and failed check with its label exactly as printed. Commands and output labels must be taken from the documentation for your installed version, as they vary between releases. Done means you have a saved report that lists the scheduler and worker status, and you can name the first check that failed.
Check scheduler status for each site
Run the scheduler status command for each site on the bench, because the scheduler can be enabled on one site and paused on another. Ask whether any site was put into maintenance mode, restored from a backup, or migrated, since those actions often pause the scheduler. Done means you have a per-site table showing whether the scheduler is enabled, and you know which sites are affected. If a site reports it is disabled, do not re-enable it yet; continue to the next steps to find out why it was stopped.
Review pending and queued jobs
List the pending background jobs for each affected site and count them by queue and job method. A large backlog in the default or long queue usually means workers are not consuming jobs, while an empty queue with no scheduled runs suggests the scheduler itself is not enqueuing. Look at the oldest queued job's timestamp to estimate how long the stall has lasted. Done means you have a count of pending jobs per queue and the oldest timestamp recorded. Keep the job list for comparison after the fix.
Read the Scheduled Job Log for the failing job type
Open the Scheduled Job Log in the desk and filter it to the job type that stopped, such as auto repeat, email, or backup. Read the status, the last run time and any traceback stored for failed runs. Compare the most recent successful run with the first failure, since the first error often points to the real cause. Done means you can name the job type, its last successful run, and the exception text of the first failure. If no entries exist at all, the scheduler is not reaching this job, which points back to the previous step.
Check worker and scheduler logs on the host
On the host, review the worker and scheduler log files for errors around the time of the first failed run. Check that the scheduler and worker services are running under the expected service manager and user, and look for permission, database connection, Redis or memory errors. The log file locations and service names depend on how ERPNext was installed, so confirm them against the documentation for your version and deployment method. Done means you have matched each host-level error to a timestamp in the Scheduled Job Log or the job backlog.
Fix one cause and verify with a test job
Change one thing at a time, such as restarting a stopped service, re-enabling the scheduler on a site, or correcting a configuration error that the logs identified. Then enqueue a harmless test job or wait for a short scheduled job to run, and confirm it appears in the Scheduled Job Log with a success status. Review the pending job count again to confirm the backlog is draining. Done means the test job completed, the backlog is shrinking, and the bench doctor report is clean on the checks that failed earlier. Record the cause and the fix for your operations notes.

What purging jobs can break

Clearing queued or pending jobs removes work the scheduler would otherwise run, and Frappe does not replay it for you. Each risk below is something to confirm on the affected site before any purge runs, not after.

Lost scheduled emails and backups

Queued emails, auto repeat documents and scheduled backup jobs that are purged will not re-run on their own. Before purging, list which scheduled jobs belong to which site and note which business events depended on them, such as a reminder to a customer or a nightly backup. Then decide who re-creates or re-sends each item, and confirm that a backup job exists and has completed recently.

Duplicated work after re-queue

If a job ran partway and was then re-queued, a second run can post the same entries, send the same email twice or regenerate files that were already produced. Check the Scheduled Job Log and the document history for the last completed step before deciding to re-queue anything. Confirm that the job is idempotent, or that you have a clear way to detect and reverse duplicates.

Half-finished reports and repostings

A purge during a stock reposting, a prepared report build or a closing run can leave partial output or a document flagged as in progress. Identify any long-running job in the queue first, and confirm whether it wrote data or only computed results. Restart these jobs only after you have checked which records changed, because a half-applied repost can distort valuation.

State mismatch after purging the wrong site

Scheduler and queue state is recorded per site, so purging on one site can leave another site's jobs untouched while the first site's documents still expect them. Run the status check for each site by name, confirm the site in the command output, and compare the pending list with what you expect before and after. Record which site was affected in your change log.

Recorded backup and dry-run review

A purge is not reversible from inside the application, so take and verify a database and files backup before running it. Review the list of jobs that would be removed, and save that list with the backup reference. Agree the review with the person who owns the affected business process, since they know which jobs are safe to drop and which must be re-created.

Reading the Scheduled Job Log for repeat failures

The Scheduled Job Log answers one question well: did a scheduled job run, and what did it report? Open it in the desk and filter by the job type (for example, the auto repeat or email-related jobs) rather than reading the list from the top. A single failed entry during a worker restart or a brief database outage is usually a one-off. Three or more failures of the same job type at a regular interval point to a recurring cause. Note the timestamps in the same column order each time, because the spacing between runs tells you whether the job is failing on every cycle, only at certain hours, or only after something changed.

For each recurring failure, record four facts: the job type, the time of the first failure, the exact error text, and what changed shortly before that time. Check the deployment log, any recent edits to the email account or outgoing SMTP password, and the worker restart times in the server logs. If the first failure lines up with a deployment or a mail setting change, that is your leading hypothesis. Write these facts into a short root-cause note with the site name, bench path, Frappe and ERPNext versions, and the list of entries, so an internal engineer or a partner can reproduce the failure without asking you to recall it. Confirm the version numbers from your own bench before you write them down.

The log only shows what ran and what the job reported when it finished or failed. It does not prove a job is healthy. A job can be absent from the log because the scheduler is disabled for that site, because the workers are not processing the queue, or because the job is queued but never picked up. Treat a missing entry as a question, not as evidence of success. Confirm the job is scheduled and the scheduler is active on the affected site before you close the investigation, and plan a periodic check that a known job has produced a fresh entry.

Security and operations considerations while fixing the scheduler

Changing scheduler state on a production ERPNext touches every automated process the business relies on, from recurring invoices to backups. The cards below cover who may act, how changes are controlled, what the logs expose, and how to test and record each step before and after a fix.

Limit who runs bench commands

Commands such as bench doctor and the scheduler enable or disable commands run with access to every site on the bench. Restrict shell access to a small named group, and require that each fix is run by someone who can explain the command and its effect on the target site. Confirm the exact flags and site arguments against the bench version you run before executing anything in production.

Gate purging of pending jobs

Purging pending jobs deletes queued work, so a purge can silently drop auto repeat invoices, reminder emails or scheduled exports. Treat it as a change that needs a written reason and a second reviewer, and record the queue contents before and after. Ask whether any queued job is needed for a known business process before clearing it.

Put the scheduler under change control

The scheduler and background workers are production services and should follow the same change process as the web tier, including ticketing, maintenance windows and rollback steps. Record which process supervisor, service unit or container runs the scheduler and which team owns it. Make sure the on-call runbook names that owner so a restart is not an improvised action.

Protect logs with personal and financial data

Scheduled Job Log entries, Error Log records and worker logs can include document names, customer or supplier details, and amounts from the failed job. Limit desk access to these logs by role, and redact or avoid copying them into tickets, chat or external support requests. Confirm where server logs are stored and who can read them before sharing an excerpt.

Test the fix on a copy first

Restore a recent backup to a non-production bench and reproduce the stuck state there before changing production. Compare how pending jobs, scheduler status and the Scheduled Job Log behave on the copy, and confirm that the fix does not replay a large queue of old jobs against live data. Note that the restored copy must not send real emails or call live integrations unless those are disabled first.

Confirm backups before every change

Take a fresh database and file backup and verify that it restores before running any scheduler command or purge. Keep the backup until the jobs have run through at least one full cycle, including any backup job itself. If the scheduler has been stopped for a long time, a backup taken at the start of the fix is the reference point for recovery.

How much effort and outside help does a scheduler fix take?

How long does it take to diagnose a scheduler that has stopped running jobs?

Diagnosis time depends mostly on how many sites and benches are affected, whether the failure is a stopped scheduler or a backlog of jobs, and how much log history survives. A single site with a clear error in the Scheduled Job Log is usually quicker to trace than a fleet where the scheduler was disabled on some sites by a configuration change. Before you request a quote, ask the provider to confirm how they will time the investigation, which environments they will access, and whether they will report findings in writing before any change is made. We cannot give a typical duration from supplied data, so treat any figure you hear as something to verify against the written scope.

What does our team need to provide for a scheduler fix?

Expect to provide shell access to the bench host with a user that can run bench commands as the Frappe user, read access to the logs, and a window in which the scheduler can be stopped and restarted. You also need a recent, tested backup of each affected site before any purge or configuration change. Someone who knows your site names, the supervisor or systemd setup, and whether Redis and workers run on the same host will shorten the work. If you run Frappe Cloud, the access model is different, so confirm what the platform exposes to you.

Can our own team fix scheduled jobs using the Frappe documentation?

Yes, for a single bench with a clear cause, an in-house engineer who is comfortable with Linux services and the Frappe command line can work through the documented checks: bench doctor, the pending jobs list, the scheduler status per site, and the Scheduled Job Log. Outside help becomes more valuable when several sites share a bench, when the cause sits in a custom app or a server script, or when a purge would remove jobs that someone still depends on. Whichever route you take, record the state before you change anything so you can explain the outcome later.

What does a fixed-scope engagement cover compared with an ongoing retainer?

A fixed-scope engagement covers a defined set of work agreed in writing before it starts: for example, diagnosing the scheduler on named sites, applying the agreed fixes, and documenting the result. Each deliverable and timeline is set in advance. A retainer covers continuing work such as monitoring, upgrades, patching and responding to incidents over an agreed period. If scheduler failures recur, a retainer suits teams that want the same people to watch the logs and respond. Ask each provider which of these items sit inside the written scope and which would be charged separately.

What does a quote for this work depend on?

A quote follows from the written scope. The main inputs are the number of sites and benches affected, the hosting model (self-hosted or Frappe Cloud), whether custom apps or server scripts are involved, the access and maintenance windows you can offer, and whether you want a one-time fix, documentation, or ongoing support. Ask for the quote to list the diagnostic steps, the change steps, the verification steps, and any work you must perform yourself. Self-hosting ERPNext is free according to the ERPNext pricing page, so any cost you pay for a fix is for labor and hosting, not for the software license.

Does a Frappe Cloud support plan change who fixes scheduler problems?

Yes, it can. According to Frappe's supported versions policy, customers must be on a listed version and subscribed to a matching Frappe Cloud support plan to receive warranty coverage from Frappe. Frappe Cloud shared site hosting starts at 5 US dollars per month, according to the ERPNext pricing page. Confirm with Frappe which issues their plan covers and which fall to your own team or a partner. For version planning, ERPNext and Frappe Framework version 14 reached end of life on January 31, 2026, version 15 is planned to be supported until the end of 2027, and version 16 until the end of 2029, according to Frappe's supported versions page.

Which version support dates should we check before scheduling a fix?

Check your running version first, because the answer changes the support path. According to Frappe's supported versions page, ERPNext and Frappe Framework version 14 reached end of life on January 31, 2026. Version 15 is planned to be supported until the end of 2027, and version 16 until the end of 2029. If you run version 14, plan an upgrade alongside the scheduler work, and ask any provider how they will test the scheduler after the upgrade. Confirm the current status on the supported versions page before you sign anything.

Limits to confirm in your environment

Scheduler fixes depend on facts about your version, hosting model and service layout that change the commands and the people who can act. Confirm these six items first, because each one decides whether the steps that follow apply to you as written.

Frappe and ERPNext version

Record the exact Frappe and ERPNext versions on every bench, then check that both sit on a release listed as supported. A version that has reached end of life receives no fixes for scheduler defects, so the fix may be an upgrade rather than a configuration change. Note the minor release too, since scheduler behavior has changed between patch releases on supported lines.

Frappe Cloud or self-hosted

Confirm whether the site runs on Frappe Cloud or on servers you operate. On Frappe Cloud, the platform team usually controls the scheduler, workers and bench settings, so your change request goes to them. On a self-hosted bench, your own operators run the commands, which means they also own the restart and rollback steps.

Scheduler and workers as separate services

Check whether the scheduler and the background workers run as separate processes or containers, and which hosts run each. Some installs start both from one supervisor config, while others split them across services. A stopped scheduler and stalled workers produce similar symptoms, so identify each process before you restart anything.

Exact bench and Frappe command output

Run the diagnostic commands on your own version and keep the output, because flags, output format and available subcommands differ between releases. Use the bench doctor output and the scheduler status output for each site, not examples from documentation. Attach this output to any vendor ticket or change request, since it is the evidence support teams need first.

Server Scripts enabled or not

If a scheduled job calls a Server Script, confirm that the server_script_enabled setting is on for that site. From version 15, Server Scripts are disabled by default, so a job can appear to stop when the script never runs. On Frappe Cloud public shared benches, Server Scripts are not allowed, so the job must move to a custom app or another mechanism.

Backup and restore before purging

Before you purge pending jobs or clear the Scheduled Job Log, confirm that you have a recent database and files backup and that someone has tested a restore on a non-production copy. Purging removes queued work that may include auto repeat documents, email sends or backup tasks, and a purge cannot be undone from inside the site. Agree who approves the purge and record what was queued beforehand.

How DeployOpen scopes and supports scheduler fixes

DeployOpen approaches scheduler problems in ERPNext as a bounded piece of work on infrastructure you control, starting from the evidence on your running site. We plan, implement, document and support self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks, and the scheduler fix follows the same written process.

How we scope

Written scope names the affected sites, the jobs that stopped, and the environment where fixes apply.
We agree which evidence to collect first, such as bench doctor output, pending job counts and the Scheduled Job Log.
Engagements are fixed-scope, so deliverables and timelines are agreed in writing before any work starts.
Quotes follow from the written scope, so ask for the affected site count and deployment method in your request.

How we build

We confirm scheduler status per site and whether the background worker and scheduler services run in your deployment.
Changes to queued jobs, such as purging stale entries, are made after a backup and a review of what will be removed.
We test that auto repeat, scheduled emails and backups run on each site after the fix, using your own schedules.
Where the cause sits in custom server scripts or custom apps, we document the change for your development team.

How we hand over

You receive a runbook covering the checks, commands and log locations used to diagnose the scheduler on your sites.
The handover records what was changed, on which sites, and how each change was verified.
We walk your operations team through the Scheduled Job Log and the alerts they should watch going forward.
Open items and any environment limits, such as hosted platforms that restrict server-side code, are listed in writing.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after the initial fix.
A retainer can cover periodic checks of scheduler health on each site and review of new failed job entries.
Upgrades to supported ERPNext releases are planned and tested as separate work with their own written scope.
Ask us to confirm which support terms apply to your deployment before you sign the written scope.