Why EspoCRM scheduled jobs stop running and what to check first
When inboxes stop updating or workflows stop firing on a running EspoCRM, the first suspect is the job runner. EspoCRM background jobs depend on either a cron entry or scheduled task that calls the application every minute, or on the EspoCRM daemon, and most failures trace back to that runner rather than to the email account or workflow itself. Check the runner before you edit any mailbox, workflow or entity setting, because a stopped runner makes healthy configuration look broken.
This diagnosis is needed when email fetching lags or halts, when scheduled workflows and time-based actions miss their runs, or when queued jobs pile up without finishing. The EspoCRM server configuration docs list PHP 8.3 to 8.5, MySQL 8.0 or newer, MariaDB 10.6 or newer or PostgreSQL 15, served by Apache, Nginx or IIS, and they state that cron or a scheduled task is required for background jobs. Confirm your versions against that list first, since an unsupported PHP or database version can stop the runner without an obvious error. Workflows and BPM processes come from the Advanced Pack, which provides reports and Business Process Management and workflows, so if your automations live there, the same runner governs them.
This page covers the sequence to follow: confirming which runner your instance uses, checking that the web server user can execute the job, reading scheduled job status, clearing stuck jobs, and reviewing parallel processing settings. Decide before you start who owns the server, since changing the crontab or daemon usually needs infrastructure access that the CRM administrator may not have. Keep a record of what you change, because a restart or a manual job run can mask the original fault. Where you cannot tell from your own environment which runner is active or which PHP version is in use, confirm it on the server before you change anything.
Cron, daemon and parallel processing options and when each fits
This table compares the three ways EspoCRM work can be processed: cron-driven execution, the daemon and parallel process settings. Read each row to see what the option is for, what the server must provide and where it tends to cause trouble. Confirm daemon and parallel settings against the server configuration docs for your EspoCRM version before you change anything.
| Option | What it is for | What it needs from the server | Trade-off |
|---|---|---|---|
| Cron job | Runs EspoCRM scheduled jobs, email fetching and workflow processing at fixed intervals | A crontab entry for the web server user that calls the EspoCRM cron script every minute | Simple to set up, but work waits for the next run and a slow run can delay the next one |
| Daemon | Keeps a long-running process that picks up queued jobs without waiting for the next cron tick | A process manager or service definition that starts and restarts the daemon under the web server user | Faster pickup of queued work, but a stopped daemon fails silently unless you monitor it |
| Parallel job processing | Lets several job processes run at once so one long job does not block the queue | Enough CPU, memory and database connections for the extra processes, plus the setting enabled in administration | Higher throughput, but more load on the database and more risk of two processes handling the same record |
| Cron only, no parallel processing | Small instances with few users, a light email load and few workflows | Only the crontab entry and a working PHP command line environment | Lowest operating effort, but backlogs appear first when volume grows |
| Daemon with parallel processing | Busy instances with heavy email fetching, mass email or many workflows | A supervised daemon, sized database connections and monitoring of the job queue | Best throughput for growing load, with the most settings to verify and maintain |
| Manual CLI run | Diagnosing a stuck job or clearing a backlog once | Shell access as the web server user, run from the EspoCRM installation directory | Useful for testing, not a substitute for a scheduled mechanism |
How to diagnose a stopped EspoCRM job runner
This sequence confirms whether EspoCRM's background job runner is scheduled, running as the right user, and processing work, so you can tell a missing trigger from a stuck job. Each step ends with a check that tells you whether to move on or fix something first.
Confirm the cron entry or scheduled task exists
Log in to the server as the administrator who manages the EspoCRM host and list the crontab for the web server user, or open the scheduled task list on Windows-based hosting. EspoCRM needs cron or a scheduled task to run background jobs, so the entry should call the EspoCRM cron script every minute as documented in the server configuration guide. Confirm the path points to the instance you are troubleshooting, not a copy or an old directory. You are done when the entry is present, points to the correct EspoCRM directory, and is not commented out.
Verify the web server user and PHP path
Identify which user the web server runs as, for example through the process list or the Apache or Nginx configuration, and confirm the cron entry runs as that same user. Then check which PHP binary the cron entry calls and compare its version with the one serving the web application, since the server configuration guide lists supported PHP versions. Run a quick version check from the same user context. You are done when the cron user, the PHP binary and the web PHP version all match and fall within the supported range.
Check file permissions on the EspoCRM directory
As the same user the job runs under, confirm it can read the EspoCRM directory and write to the data, cache and log directories. Ownership problems often appear after a restore, a manual file copy or an upgrade run as root. Look for permission errors in the cron output or the EspoCRM log files when the job is triggered. You are done when the job user can create and modify a test file in the writable directories and the log shows no permission errors on a manual run.
Review scheduled job status in the admin panel
Sign in to the EspoCRM administration panel with an administrator account and open the scheduled jobs section. Review each job's last run time, status and any error messages, and compare the timestamps with the current time. A job with an old last run time while cron appears correct points to a trigger or permission problem, while recent runs with failed statuses point to job-level errors. You are done when you know whether the runner is firing at all and which specific jobs are failing or idle.
Look for jobs stuck in running state
In the same scheduled job view, identify jobs that show a running state for much longer than their normal execution would take, and note their start times. A job left in running state after an interrupted process, such as a killed PHP process or a server restart, can block the queue for that job type. Before changing anything, check the log for the process that started it and make sure no other run is still active. You are done when you have a list of stuck jobs with start times and confirmed that no active process owns them.
Check parallel processing settings
Open the system settings in the administration panel and review the job processing and parallel process options, along with any daemon configuration on the host. If several cron or daemon processes run at once, confirm the settings match how many processes you intend to run, since overlapping runners can contend for the same jobs. Make a note of the current values before editing anything. You are done when the configured process count matches the running processes you see on the host and the notes record the original values.
Run a job from the command line to confirm completion
As the web server user, change into the EspoCRM directory and run a single job or the job processing command from the command line, then watch the output. Choose a non-critical job first, such as a cleanup task, so you can observe completion without side effects on live data. Check the scheduled job status again and the EspoCRM log for errors. You are done when the command exits without error, the job status records a completed run with a current timestamp, and the log shows no new failures. If it still fails, the problem is in the job or its data, not the trigger.
Common causes when workflows and email fetches silently stop
When EspoCRM stops fetching email or firing workflows, nothing usually throws a visible error in the UI. The causes below share one pattern: the job runner is not executing, or it is executing but cannot finish. Check them in order, starting with the cheapest test.
Cron entry missing or under the wrong user
EspoCRM needs a cron or scheduled task to run background jobs, and the entry has to run as the user that owns the EspoCRM files and can write to its cache and logs. A crontab added under root, or removed during a server migration, produces the same symptom as a stopped daemon: jobs stay queued. First check: list the crontab of the web server user and confirm the EspoCRM cron line is present and points at the correct installation path.
Web server user lacks file permissions
Jobs run as the web server user, so that user needs read access to the application and write access to the directories EspoCRM uses for cache, logs, uploads and data. A deployment copied from another host, or files restored with a different owner, often lets web requests work while background processing fails silently. First check: compare the owner of the EspoCRM directory and the data and custom folders with the user shown by the process list for the web server, and read the newest entries in the EspoCRM log.
Stuck job blocking the queue
A single job that hangs, for example a mailbox connection that never times out or a workflow waiting on a failed external call, can hold a process slot and delay everything queued behind it. The Scheduled Job list in the admin panel shows status and last run time, so a job marked as running for hours is a strong signal. First check: open the scheduled job log and identify jobs in running state with old start times before restarting anything, so you can record which job hung and why.
Parallel processes set too low
Parallel processing lets EspoCRM run several queued jobs at once. When incoming mail volume or workflow activity grows beyond what one or two processes can clear, jobs accumulate and reach users late, even though every job eventually completes. Confirm the value in the admin settings against your actual volume before raising it, and watch database load after each change. First check: compare the queue length and job wait times in the scheduled job log during a busy period with the configured parallel process count.
Daemon not restarted after reboot
Where the daemon is used instead of cron, it must be started as a service that comes back after a server restart. A daemon started by hand in a terminal session stops when the session ends, and a host reboot leaves no process at all. Mail and workflows then resume only after someone notices. First check: confirm the daemon is registered with the service manager on your host, is enabled at boot, and is currently running under the same user as the web server.
PHP version mismatch after an update
EspoCRM's server configuration lists supported PHP versions, and the CLI that cron calls may resolve to a different PHP binary than the one Apache, Nginx or PHP-FPM uses. After an operating system update or a PHP upgrade, web pages can keep working while cron runs an older or unsupported interpreter. First check: run the PHP version command as the cron user and compare it with the version the web application reports in the admin panel, then confirm both fall within the supported range.
How to recognize and clear stuck jobs safely
A scheduled job that stays in a running state after a crash, a server restart or a timeout can block the jobs that come after it. EspoCRM records each job in its scheduled job queue, and while a job appears to be running, the processing loop may skip similar work rather than start it again. The symptom is familiar: emails stop fetching or a workflow stops firing, yet cron or the daemon is clearly alive. Before you touch anything, open the scheduled job list in the admin panel and look for entries with a running status whose start times are well in the past. Compare them with the job log and your server logs for the same time window to confirm whether the process that owned the job still exists.
Do not delete or edit the record first. Confirm the job's type, its target entity and its parameters, and check whether a PHP process for the EspoCRM command is still active on the server. If no process exists and the job has not progressed, the record is a candidate for reset. Changing the status of a job while a worker is still executing it can produce duplicate actions, such as a second email send or a repeated workflow step, so make sure the job is not actually in progress. Where the docs describe a command for running or inspecting jobs from the CLI, use that path for diagnosis and follow the version-specific guidance in the EspoCRM docs: Server configuration page.
Take a full backup of the database and the instance files before you clear any state, because a reset is hard to reverse once dependent work has run. The backup procedure is covered on the EspoCRM backup and restore page, and you should confirm that a restore has been tested on a separate host, not only that a dump file exists. After the reset, watch the next scheduled run and confirm that the job completes and that the related records changed as expected. If the same job sticks again, treat it as a recurring fault and investigate the cause in the logs rather than repeating the reset.
Security and access considerations for the job runner
The job runner executes EspoCRM code with the permissions of a system account, so who can edit its schedule, who owns the files and who can act as an administrator all shape the risk. The cards below cover the controls to review before you change anything about cron or the daemon.
Web server user file permissions
The account that runs PHP for the web server, and any cron entry that runs EspoCRM commands, should own the application files it must write to, such as cache, data and custom directories, and should not own the rest of the tree. If a job fails with permission errors after a fix, check which user ran the command, because a cron entry run as root can leave root-owned files that the web user cannot update later. Confirm this on your own host, since layouts differ between Docker and bare-metal installs.
Limiting who edits crontab
A crontab entry runs whatever command it contains on a schedule, so anyone who can edit it can change what EspoCRM runs and as which user. Restrict crontab edits for the web or application user to a small set of named operators, and record each change in your change process. Review existing entries during the fix, because an old or duplicated entry can cause the same job to run twice.
Keeping admin accounts out of daily work
The security guidance recommends avoiding admin accounts for daily work, so troubleshooting should use a separate admin account reserved for maintenance. Do not run ad hoc job commands while signed in as a day-to-day admin in the browser. Keep one break-glass admin account with a strong password and documented custody, and review who holds admin rights when a job fix is complete.
Restricting access to the server
Shell access to the host that runs cron or the daemon is effectively control of the CRM, since it can read the configuration and database credentials. Limit SSH to named administrators, use key-based login, and check that the job runner logs do not expose secrets. Confirm the exact file locations and permissions with your own hosting team.
Logging job runs and changes
After a fix, you need evidence of what ran, when, and under which account. Keep the scheduled job log entries and the system log together with the crontab change record so that a stalled job can be traced back to a specific edit. Decide how long these logs are kept and who can read them, since they can contain record identifiers and email addresses.
Questions teams ask before fixing or outsourcing job processing
Can an internal admin fix EspoCRM scheduled jobs without a partner?
Often yes, if someone on the team has shell access to the server, can read the web server and PHP logs, and understands how the cron entry or daemon runs under the web server user. The usual fault sits in one of three places: the cron entry is missing or runs as the wrong user, the daemon is not running, or jobs are stuck in a running state after a crash. Work through the scheduled job list in the admin panel and the job logs before changing anything. Teams without that server access, or without someone comfortable reading logs, usually get further with a partner who can review the setup in one session.
How long does diagnosing a stuck EspoCRM job queue take?
Duration depends on the drivers that shape the investigation, not on a standard figure. The main ones are how quickly you can reach the server and the admin login, how many scheduled jobs and workflows exist, whether jobs fail with errors or simply queue up, and whether the instance runs in Docker, on a bare server or behind a reverse proxy. Large job volumes and parallel processing settings add time because each change has to be observed over several cycles. Ask any provider to state the diagnostic steps and the access they need before agreeing to a timeline.
What access and change window does a job processing fix require?
The work needs four things from the client: shell access to the EspoCRM host or container, an admin login to the EspoCRM instance, read access to the relevant logs, and a window in which cron, daemon or parallel processing settings can be changed and restarted. Restarting the daemon or editing scheduled tasks can interrupt email fetching and workflows briefly, so agree the window in advance. If the instance is in a regulated environment, confirm which change approvals and access records apply before the engagement starts. Ask the provider to list every system they will touch and every account they will use.
Do workflows in EspoCRM need the Advanced Pack to fire?
Workflows and Business Process Management are part of the Advanced Pack, an official add-on that EspoCRM describes as included in all EspoCRM Cloud plans. On a self-hosted instance, the pack must be installed and licensed before its workflows exist, so a workflow that does not fire may be a missing extension rather than a job fault. Confirm first whether the Advanced Pack is installed and whether its workflow jobs appear in the scheduled job list. Check the current licensing terms with EspoCRM before planning, since they determine what your team can deploy.
What does a partner's quote for fixing scheduled jobs depend on?
A quote follows from a written scope, so it depends on what the provider must verify and change. The main inputs are the deployment method, the number of scheduled jobs and mailboxes affected, whether email fetching, workflows or both are failing, the state of the database and logs, and whether the fix stays on the current version. Ask for the diagnostic phase and the remediation phase as separate line items, the access and change window assumed, and what is delivered at the end, such as a documented cron or daemon setup and a runbook. DeployOpen does not publish a price list; a quote is produced from that written scope.
Is cron or the daemon the better choice for EspoCRM background jobs?
The right choice depends on how the instance is hosted and how much job volume it carries. EspoCRM's server configuration documentation says cron or a scheduled task is required for background jobs, and the daemon is an additional process that can run jobs in parallel. Cron is simpler to audit and works on most hosts, while the daemon suits higher volume but must be kept running under a supervisor. Pick one approach per instance, verify it runs as the web server user, and avoid running both in ways that process the same queue twice.
How do you confirm EspoCRM jobs are running after a fix?
Confirm the fix with evidence from the running system, not from the configuration alone. Check that the scheduled job status shows recent runs, that no jobs remain in a running state beyond their expected duration, and that a test email arrives in a monitored mailbox and a test workflow fires. Review the EspoCRM logs and the cron or daemon logs across several cycles, including a period of peak load. Record the results in a runbook so the next person can repeat the checks.
Should a team fix job processing before a version upgrade?
Usually yes, because a broken job queue hides upgrade problems and makes it harder to tell whether an upgrade fixed or broke email and workflows. Stabilize cron or the daemon first, confirm the job log is clean, then plan the upgrade with a current backup. Check which PHP version and extensions the target release requires, since the server configuration documentation lists supported PHP and database versions. Review the upgrade notes for your exact version before scheduling any change.
When a partner should take over the job runner
Bring in a partner when scheduled jobs keep failing after the basic checks pass, or when the cause sits in the platform around EspoCRM rather than in one setting. Internal staff can usually restart a stuck job or confirm that a crontab entry exists. Escalate when the same jobs stall again within days, when email stopped updating right after a server move or database import, or when the job runner has to coordinate across several web servers, worker hosts or Docker containers. Each of those changes which process owns the queue, which user runs it and where the lock files and logs live, so a fix that works on one host can quietly break another.
Escalate sooner if the PHP version or database version has changed recently. The EspoCRM server configuration docs list supported PHP versions (8.3 to 8.5) and database versions (MySQL 8.0 or newer, MariaDB 10.6 or newer, or PostgreSQL 15), and a runtime outside that list can make jobs fail without an obvious error. Upgrades also change the CLI behavior that cron and the daemon depend on. Before any upgrade, ask whether the team has a written rollback path and a restore that has been tested, because a job runner problem found after an upgrade is often hard to separate from a half-finished migration.
A partner's review usually covers the evidence first: the crontab or systemd entries and the user they run as, the daemon's process status, the scheduled job records and their last run times, the log entries for failed jobs, the PHP and database versions in use, and the parallel processing settings. It then looks at how the instance is hosted, including reverse proxy and file permission layout, and what changed in the weeks before the failures started. The output is typically a findings list with recommended changes and the steps needed to verify them. Ask any partner to state in writing what the review covers, what it will not change without approval, and what they need from your team. No review can promise that jobs will stay healthy, so ask how monitoring of job runs will be handed over.
How DeployOpen works on this
DeployOpen starts by reading how your EspoCRM runs jobs today, then fixes the cause inside your own infrastructure. Each engagement is fixed-scope, with the scope, deliverables and timeline agreed in writing before any change is made to your instance.
How we scope
- We review how your instance runs background jobs: crontab, daemon, or both, and which user the web server runs as.
- The written scope names the affected functions, such as email fetching, workflows or scheduled reports, and the evidence we will collect.
- We agree in writing what is out of scope, including unrelated mail server, identity or network changes.
How we build
- We check scheduled job status, stuck jobs and parallel processing settings against your expected job volume before changing anything.
- We take a backup first, then apply the cron or daemon fix, correct file ownership and job settings in a staging copy where possible.
- We test each affected job end to end, such as an inbox fetch or a workflow trigger, and record the results.
How we hand over
- You receive a written record of the root cause, the changes made and the commands or configuration keys touched.
- We document how to check job health, read the scheduled job log and run jobs from the CLI for future troubleshooting.
- Your team walks through the runbook with us so the fix is repeatable without us on site.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer if job processing needs regular attention.
- Retainer scope, response expectations and reporting are agreed in writing, and quotes follow from the written scope.
- Ask us to confirm which EspoCRM version and PHP version your instance runs before any retainer or upgrade planning starts.
