bookmark_borderTroubleshooting Background (async) Processing Issues

About

The background (async) processing feature was introduced in Gravity Forms 2.2. It is currently used by the following:

  • Feed processing by add-ons which extend the Gravity Forms feed add-on framework (GFFeedAddOn) and have declared that asynchronous feed processing is supported, such as the Webhooks Add-On.

    If you are developing a GFFeedAddOn based add-on and want to use background processing see the $_async_feed_processing article.

    If you want to use background processing with a GFFeedAddOn based add-on which does not currently support background processing, see the gform_is_feed_asynchronous article.

  • The Gravity Forms 2.3 database upgrade.

For background processing to work the following requirements must be met:

  • The site needs to be able to send a post request to it’s Admin Ajax URL using the WordPress HTTP API to trigger processing of queued tasks.
  • The site needs to support cron jobs so the background processors healthcheck can restart processing of queued tasks if processing stops for some reason or if the request to Admin Ajax fails.

Logging

Begin troubleshooting by:

(1) Enable logging on the Forms > Settings page
(2) On the Forms > Settings > Logging page, ensure that Gravity Forms Core and any add-ons are enabled and set to log all messages.

Check our logging and debugging documentation for additional help.

As logging statements are only recorded when the functions they are contained within are run, perform the steps needed to replicate the issue such as submitting the form or running the database upgrade from the system status page.

Example logging statements to look for in the Core log:

GF_Background_Process::dispatch(): Running for [gf_feed_processor or gf_upgrader].
GF_Background_Process::schedule_event(): Scheduling cron event for [gf_feed_processor or gf_upgrader].
GF_Background_Process::dispatch(): Unable to dispatch tasks to Admin Ajax: [message here].
GF_Background_Process::maybe_handle(): Running for [gf_feed_processor or gf_upgrader]. (Only if Admin Ajax triggers processing)
GF_Background_Process::handle_cron_healthcheck(): Running for [gf_feed_processor or gf_upgrader]. (Only if the cron triggers processing)
GF_Background_Process::handle(): Running for [gf_feed_processor or gf_upgrader].
GF_Background_Process::handle(): Processing batch for [gf_feed_processor or gf_upgrader].
GF_Background_Process::handle(): Batch completed for [gf_feed_processor or gf_upgrader].

Example logging statements to look for in the 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 statement 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(…)

Admin Ajax request fails

If you find a logging statement like the following in the core log your site is unable to contact itself using the WordPress HTTP API, you’ll need to contact your web host so they can look into why that is.

GF_Background_Process::dispatch(): Unable to dispatch tasks to Admin Ajax: cURL error 7: Failed to connect to [site-domain-here.dev] port 443: Connection refused

If you are testing locally using the Local by Flywheel app and the site is using HTTPS see the following topic: https://local.getflywheel.com/community/t/curl-error-when-accessing-ssl-local-site/2940/8

Cron jobs not running

The cron jobs should only run if processing by Admin Ajax can’t be started, or if Admin Ajax stops processing the tasks before the queue has been cleared.

Visit the Forms > System Status page. See the Checking Your Environment Details article.

In the WordPress Environment section of the report, WordPress Cron or WordPress Alternate Cron should be enabled. If both are disabled, try setting DISABLE_WP_CRON to false in the wp-config.php file e.g.

define( 'DISABLE_WP_CRON', false );

WP Crontrol Plugin

If you are still having issues, install the WP Crontrol plugin by John Blackbourn.

Visit the Tools > Cron Events page. The plugin will display a warning message at the top of the page if your cron system doesn’t appear to be working (for example if your server can’t connect to itself to fire scheduled cron events).

If you don’t see a warning message check the table to see if any of the following jobs exist:

wp_gf_upgrader_cron
wp_gf_feed_processor_cron

Some sites may use a different prefix instead of the wp prefix shown in the above names.

If you do find the job, try clicking the run now link which is located to the right of the Recurrence column, and then check the logs in a few minutes to see if the tasks were processed.

Create a real cron job

If you find the cron is unreliable your site may not be receiving enough traffic for WordPress to process the cron jobs, you may need to create a real cron job in your hosting control panel. See this article.