Introduction
The background (async) processing feature was introduced in Gravity Forms 2.2.
Background processing uses a separate request to process tasks without blocking the current operation, such as a form submission.
The four known background processors are:
- Database upgrades, versions 2.3+.
- Telemetry, versions 2.7.13+.
- Feed processing by add-ons which extend the Gravity Forms feed add-on framework (GFFeedAddOn) and have declared that asynchronous feed processing is supported. For more details, see Add-On Support for Background Feed Processing.
- Gravity PDF (versions 5.0+), by Blue Liquid Designs, can process notifications that include PDFs in the background, so form submission completion is not delayed.
- Since version 2.6.8.3, the gform_is_asynchronous_notifications_enabled filter can be used to enable background sending of notifications, to speed up form submissions.
How can I verify that my site supports background processing?
For background processing to work, the site needs to be able to send a post request to its Admin Ajax URL using the WordPress HTTP API to trigger processing of queued tasks.
Check the Site Health
Go to the Tools > Site Health page of your site admin and check for the following under Passed tests:
- Scheduled events are running
- HTTP requests seem to be working as expected
- Your site can perform loopback requests
If any of those are not listed under Passed tests, your site might have issues processing background tasks.
Check the System Status
Go to the Forms > System Status page.
In the WordPress Environment section, check that Background tasks is Yes.
For more details, see Checking Your Environment Details.
How can I verify that background tasks are being processed?
Begin troubleshooting by:
- Enabling logging on the Forms > Settings page. Don’t forget to save the settings once logging is enabled.
- On the Forms > Settings > Logging page, ensure that logging is enabled for Gravity Forms Core and all add-ons.
- Perform the steps to trigger task processing, such as submitting the form or running the database upgrade from the system status page.
- View the logs via the Forms > Settings > Logging or Forms > System Status pages.
Check our logging and debugging documentation for additional help.
Example Logging Statements
Gravity Forms Core log
Note: [processor_slug] can be gf_upgrader, gf_feed_processor, gf_notifications_processor, or slug from a third-party add-on (e.g. gravitypdf).
| Message |
|---|
| GF_Background_Process::save(): Saving batch [batch_id]. Tasks: [task_count]. |
| GF_Background_Process::dispatch(): Running for [processor_slug]. |
| GF_Background_Process::schedule_event(): Scheduling cron event for [processor_slug]. |
| GF_Background_Process::dispatch(): Unable to dispatch tasks to Admin Ajax: [message here]. |
| GF_Background_Process::maybe_handle(): Running for [processor_slug]. (Only if Admin Ajax triggers processing) |
| GF_Background_Process::handle_cron_healthcheck(): Running for [processor_slug]. (Only if the cron triggers processing) |
| GF_Background_Process::handle(): Running via [method] request for [processor_slug]. |
| GF_Background_Process::handle(): Processing batch [batch_id]; Tasks: [task_count]. |
| GF_Background_Process::update(): Batch [batch_id] updated. Tasks remaining: [tasks_remaining]. |
| GF_Background_Process::handle(): Processing task [task_number]. Attempt number: [attempt_number]. |
| GF_Feed_Processor::task(): Aborting. Add-on ([addon_slug]) not found for feed (#[feed_id] – [feed_name]) and entry #[entry_id]. |
| GF_Feed_Processor::task(): Aborting. Error occurred during processing of batch [batch_id]; Tasks remaining: [tasks_remaining]. Details: [error_message] |
| GF_Background_Process::handle(): Removing task [task_number] from batch. |
| GF_Background_Process::handle(): Batch completed for [processor_slug]. |
| GF_Background_Process::delete(): Deleting batch [batch_id]. |
| GF_Background_Process::handle(): All batches completed for [processor_slug]. |
| GF_Background_Process::clear_scheduled_event(): Clearing cron event for [processor_slug]. |
Add-on log
| Message |
|---|
| GFFeedAddOn::maybe_process_feed(): Adding feed (#[feed_id] – [feed_name]) to the processing queue for entry #[entry_id]. |
| GF_Feed_Processor::task(): Preparing to process feed (#[feed_id] – [feed_name]) for entry #[entry_id]. |
| GF_Feed_Processor::task(): Aborting. Entry #[entry_id] not found for feed (#[feed_id] – [feed_name]). |
| GF_Feed_Processor::can_process_feed(): Feed (#[feed_id] – [feed_name]) has already been processed for entry [entry_id]. Reprocessing is NOT supported. |
| GF_Feed_Processor::can_process_feed(): Feed (#[feed_id] – [feed_name]) has already been processed for entry [entry_id]. Reprocessing is NOT allowed. |
| GF_Feed_Processor::can_process_feed(): Feed (#[feed_id] – [feed_name]) has already been processed for entry [entry_id]. Reprocessing IS allowed. |
| GF_Feed_Processor::task(): Aborting. Feed (#[feed_id] – [feed_name]) attempted too many times for entry #[entry_id]. Attempt number: [attempts’]. Limit: [max_attempts]. |
| GF_Feed_Processor::task(): Starting to process feed (#[feed_id] – [feed_name]) for entry #[entry_id]. Attempt number: [attempt_number_here] |
| GF_Feed_Processor::task(): Aborting. Error occurred during processing of feed (#[feed_id] – [feed_name]) for entry #[entry_id]: [message_here] |
| GF_Feed_Processor::task(): Completed processing of feed (#[feed_id] – [feed_name]) for entry #[entry_id]. |
2.3 database upgrade
| Message |
|---|
| GF_Background_Upgrader::task(): Running callback: Array(…) |
| GF_Background_Upgrader::task(): Callback needs another run: Array(…) |
| GF_Background_Upgrader::task(): Finished callback: Array(…) |
| GF_Background_Upgrader::task(): Could not find callback: Array(…) |
Common Issues
Most issues will be related to how the server hosting your site is configured. You may need to contact your host for assistance resolving the issue.
Here are some common errors that can prevent the processing of queued tasks:
| Error Code | Description | Possible Solution |
|---|---|---|
| cURL error 6 | GF_Background_Process::dispatch(): Unable to dispatch tasks to Admin Ajax: cURL error 6: Could not resolve host: [site-domain-here] | This indicates an issue with your domain’s DNS configuration or the server hosting your site. Please get in touch with your web host. |
| cURL error 7 | GF_Background_Process::dispatch(): Unable to dispatch tasks to Admin Ajax: cURL error 7: Failed to connect to [site-domain-here] port 443: Connection refused | A problem on your server may cause this issue. Your web host might need to update server packages like PHP, cURL, or OpenSSL. If your site uses Cloudflare, its SSL settings could also be the cause. Temporarily disabling Cloudflare has resolved this issue in some cases. For a long-term solution, you may need to contact Cloudflare support. |
| cURL error 28 | GF_Background_Process::dispatch(): Unable to dispatch tasks to Admin Ajax: cURL error 28: Operation timed out after 1001 milliseconds with 0 bytes received | For assistance resolving cURL timeouts like this, please see the cURL error 28 in WordPress article. |
| cURL error 35 | GF_Background_Process::dispatch(): Unable to dispatch tasks to Admin Ajax: cURL error 35: error:14077410:SSL routines:SSL23_GET_SERVER_HELLO:sslv3 alert handshake failure | It would indicate that something is altering the URL used to send the requests. See Note 3 |
| Response code: 401 | Background tasks: No ✘ Response code: 401 | If your site is using basic authentication, you can add the Authorization header to the Ajax request using the WordPress http_request_args filter. See Note 1 |
| Response code: 403 | Background tasks: No ✘ Response code: 403 | It would indicate the server is actively blocking the request to your site admin-ajax.php file. See Note 2 |
| Response code: 404 | Background tasks: No ✘ Response code: 404 | It would indicate something is altering the URL used to send the requests. See Note 3 |
Notes
Response code: 401
Example:
add_filter( 'http_request_args', 'http_request_args_basic_auth', 10, 2 );
function http_request_args_basic_auth( $args, $url ) {
if ( strpos( $url, admin_url( 'admin-ajax.php' ) ) === 0 ) {
$args['headers']['Authorization'] = 'Basic ' . base64_encode( USERNAME . ':' . PASSWORD );
}
return $args;
}
Note: The above example assumes USERNAME and PASSWORD are constants defined elsewhere (e.g., in wp-config.php). Otherwise, include the values directly, e.g., ‘USERNAME:PASSWORD’.
Response code: 403
Common causes include:
- A security plugin or custom function added to the theme is asking the server to block access to wp-admin or the admin-ajax.php file.
- The above is blocked by .htaccess rules, often added by security plugins and not always removed when the plugin is disabled.
- There’s a server-side security module or firewall (e.g., ModSecurity) or a third-party service intercepting the request and blocking it.
Performing a manual conflict test may help to discard plugin/theme functions as the cause, as long as they don’t use .htaccess rules. Contact your host for further assistance when the manual conflict test doesn’t help.
Response code: 404
Check the following:
- Ensure your Site Address (URL) setting is correct in WordPress Settings > General page.
- Check your wp-config.php file to see if WP_SITEURL is set to a wrong URL.
- Double-check the value stored in your database under wp_options table for siteurl.
- Perform a manual conflict test.
If none of the above helps to clear the 404 error from the system status page, contact your host support for further investigation of the issue.
Backup Cron Job
Just before the background processor makes the Ajax request to process queued tasks, it also schedules a backup cron job.
This cron job is only used if the Ajax request fails to trigger processing or the request times out before the queue is cleared.
See Troubleshooting Scheduled Events for help determining if your site supports cron jobs.
Pause/Resume System
If a feed add-on encounters an error during processing, the task queue will be temporarily paused. Processing is expected to resume automatically when the fallback cron event is triggered.