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

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 CodeDescriptionPossible Solution
cURL error 6GF_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 7GF_Background_Process::dispatch(): Unable to dispatch tasks to Admin Ajax: cURL error 7: Failed to connect to [site-domain-here] port 443: Connection refusedA 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 28GF_Background_Process::dispatch(): Unable to dispatch tasks to Admin Ajax: cURL error 28: Operation timed out after 1001 milliseconds with 0 bytes receivedFor assistance resolving cURL timeouts like this, please see the cURL error 28 in WordPress article.
cURL error 35GF_Background_Process::dispatch(): Unable to dispatch tasks to Admin Ajax: cURL error 35: error:14077410:SSL routines:SSL23_GET_SERVER_HELLO:sslv3 alert handshake failureIt would indicate that something is altering the URL used to send the requests. See Note 3
Response code: 401Background tasks: No ✘ Response code: 401If 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: 403Background tasks: No ✘ Response code: 403It would indicate the server is actively blocking the request to your site admin-ajax.php file. See Note 2
Response code: 404Background tasks: No ✘ Response code: 404It 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.