Troubleshooting Background (async) Processing Issues

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:

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 to look for in the 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).

  • GFAPI::send_notifications(): Adding [count] notification(s) to the async processing queue for entry #[entry_id].
  • 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 for [processor_slug].
  • GF_Background_Process::handle(): Processing batch for [processor_slug].
  • GF_Background_Process::handle(): Batch completed for [processor_slug].

Example logging statements to look for in an add-on log:

  • GFFeedAddOn::maybe_process_feed(): Adding feed (#[feed_id] - [feed_name]) for entry #[entry_id] for [add-on_slug] to the processing queue.
  • GF_Feed_Processor::task(): already processed feed (#[feed_id] - [feed_name]) for entry #[entry_id] for [add-on_slug]. Bailing.
  • GF_Feed_Processor::task(): attempted feed (#[feed_id] - [feed_name]) for entry #[entry_id] for [add-on_slug] too many times. Bailing.
  • GF_Feed_Processor::task(): Starting to process feed (#[feed_id] - [feed_name]) for entry #[entry_id] for [add-on_slug]. Attempt number: [attempt_number_here]
  • GF_Feed_Processor::task(): Unable to process feed due to error: [message_here].
  • GF_Feed_Processor::task(): Marking entry #[entry_id] as fulfilled for [add-on_slug]

The add-on log will also include other add-on specific logging statements.

Example logging statements to look for in the core log for the 2.3 database upgrade:

  • 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: 

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 there is an issue with the DNS configuration of your domain or the server hosting your site. Please contact 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

This error usually indicates there is an issue with the SSL/HTTPS configuration of the site or server hosting the site. Please contact your web host.

If you are testing locally using the Local app and the site is using HTTPS, see the cURL error when accessing SSL Local Site topic on their forums.

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

This can be caused by an issue on the server hosting your site. Your web host may need to update some of the packages on the server, such as PHP, cURL, and OpenSSL.

If your site is using the Cloudflare service, their SSL configuration could also cause this error. Temporarily disabling Cloudflare for the site in question has been known to resolve the issue. You may need to contact Cloudflare support for assistance resolving this issue permanently.

Response code: 401

You may see the following in the System Report

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 e.g.

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;
}

The above example is based on USERNAME and PASSWORD being constants defined elsewhere (i.e., the wp-config.php file), if not, you can include the values within the quotes e.g., 'USERNAME:PASSWORD'.

Response code: 403

If you’re seeing the following in the System Report

Background tasks: No ✘ Response code: 403

It would indicate the server is actively blocking the request to your site admin-ajax.php file. Common causes for this are:

  • 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. These rules are 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 being the cause, as long as they don’t use .htaccess rules.

When the manual conflict test doesn’t help, it’s time to contact your host for further assistance.

Response code: 404

If you’re seeing the following in the System Report

Background tasks: No ✘ Response code: 404

It would indicate something is altering the URL used to send the requests.

Gravity Forms will always ask WordPress for your site admin URL in order to get the correct URL for the request, so you will want to check for the following points:

  • Check your Site Address (URL) setting is correct in your 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, it would be the time to 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.