Documentation

Background Task Isolation

Craft CMS launches background tasks in response to actions performed by users or on a schedule. These tasks are normally executed whenever a user logs into the control panel using an ajax request to trigger them.

This implementation can lead to problems if the tasks take a long time to execute or consume a significant amount of CPU as they will starve resources from normal user requests. You can read a little more about that here and here.

On our Starter plan, this standard mechanism remains the default, however our Enhanced and Pro plans provide the ability to run any background tasks completely isolated from user requests and without needing to be triggered by a user navigating around the Craft control panel.

Activating the Background Task Isolation

If your project is subscribed to a plan that supports it, you can activate background task isolation on a per-environment basis.

  1. Visit the Environment > Settings page for the environment that you'd like to change

  2. Toggle 'on' the Background Tasks option

  3. Sync your changes

  4. Your background tasks will now be executed immediately after being created and with their own pool of resources.

Problems With Background Task Isolation

Most of the time your background tasks will work fine without requiring any changes, however in testing we have found that some tasks can have problems.

Tasks assuming they are being run as a web request

Craft has two primary modes of execution: web and console. When handling web requests the core framework has access to things like session information and the URL that was used to trigger the request. When handling a console request these pieces of information aren't present.

Some background tasks (mainly those from originating from plugins) assume that all tasks will be executed as a web request and therefore try to access session or URL information. This causes the task to throw an error when being executed from a console command (which is how Servd's background tasks are executed).

This will often present itself in the logs as Session does not exist in a console request or Calling unknown method: craft\console\Request::getPathInfo().

You can determine whether or not your tasks might run into problems by setting 'runTasksAutomatically' => false in your project's config/app.php, queuing up some tasks and then executing ./craft queue/run on the command line in your project's root directory.

Tasks assume a single filesystem

Servd runs your background tasks in isolation to prevent them from interfering with normal user requests. This means that they also have an independent filesystem.

During testing we have found that some tasks assume a single filesystem is being shared between all component parts of the application. Most notably the Feed Me plugin writes all of its logs to the filesystem to later be displayed in the Craft control panel. This is not compatible with a high-availability environment and results in the logs simply not displaying in the control panel.

Resolving Problems with Background Task Isolation

First, look at the logs inn the Servd dashboard to see if anything has been logged there. Usually, any errors will be easy to find there.

If you do have problems with a task's compatibility with isolation, you can disable the setting either temporarily or permanently which will cause Craft to fall back to processing tasks using web requests on your project's user-facing instances.