Background processing
Imports, exports, and other longer-running actions in GravityKit products can run in the background when they need more time to finish.
Instead of trying to complete everything in a single page load, the job is queued and processed behind the scenes. This helps larger actions finish more reliably without forcing everything to happen in one request.
When you will see it #
Background processing is typically used for things like:
- importing entries
- generating export files
- running scheduled jobs
- processing larger batches of data
You usually do not need to do anything special. Start the import, export, or other action, leave the page if you want to, and check back later if you want to confirm that it finished.
Settings related to background processing #
These settings are on the GravityKit settings page: go to GravityKit, then Settings, select GravityKit in the list on the left, and open the Technical section.
Enable Background Processing | On by default | Lets GravityKit products run long tasks in the background. Turning it off stops background jobs for every GravityKit product. |
Show Background Jobs | Off by default | Adds a Background Jobs page under the GravityKit menu, where you can see past, current and scheduled jobs. It appears only while Enable Background Processing is on. |
Loopback URL Override | Empty by default | Background jobs rely on the site being able to send a request to itself in order to start or continue processing. By default, that request uses your normal site URL. This setting lets you replace it with a different URL if the server cannot reach the public site URL from inside the hosting environment. It appears only while Enable Background Processing is on. |
GravityImport’s Enable Background Processing setting
GravityImport has its own Enable Background Processing setting, separate from the GravityKit one above. To find it, go to GravityKit, then Settings, select GravityImport in the list on the left, and open the General section. It’s on by default, and a change takes effect once you click Save Settings.
When it’s on, imports run in the background as long as the site can send requests to itself (see Troubleshooting). When it’s off, or when those requests fail, imports run in your browser, and the import page needs to stay open until the import finishes.
To make imports run in your browser, turn off this setting and leave the GravityKit one above on.
Troubleshooting #
If background jobs are not starting or finishing, check the following.
Go to Tools > Site Health > Info and look for the GravityKit Background Processing section. This shows whether the scheduler has a working execution path and will indicate what is wrong.
Jobs don’t run
Background jobs are processed by a queue runner that sends HTTP requests back to the site. If the server cannot make these loopback requests, jobs will stay stuck.
Common causes:
- basic authentication or password protection on the site
- maintenance mode
- a security plugin blocking internal requests
- firewall or WAF rules
- proxy or load balancer configuration
- DNS or SSL issues preventing the server from resolving its own URL
To fix:
- temporarily disable basic authentication or password protection
- turn off maintenance mode
- check security plugin settings for blocked internal requests
- ask your host whether loopback or self-requests are being blocked at the server or firewall level
If the server can reach itself but at a different URL than your site’s home URL (common with reverse proxies, load balancers, or containerized hosting), ask your host for the correct internal URL and add it under settings.
If loopback cannot be fixed at all, adding define( 'ALTERNATE_WP_CRON', true ); to wp-config.php can work as a last resort. It processes cron tasks inline during page loads, which is slower but functional.
Jobs don’t run on time
Scheduled jobs may run later than expected on low-traffic sites. Background processing is triggered when someone visits the site – if no one visits, scheduled jobs wait until the next page load.
If you need jobs to run closer to their scheduled time, use an external service like FastCron, EasyCron, or a server cron to request your site at a regular interval, every 5 to 15 minutes for most sites. This keeps background processing running even when there are no visitors.
If your site defines DISABLE_WP_CRON
Some hosts, and many performance guides, add define( 'DISABLE_WP_CRON', true ); to wp-config.php and run cron externally instead. With that constant set, a normal page load no longer starts WordPress cron, so pointing an external service at your homepage does nothing and scheduled jobs stay queued.
An import or other job you start yourself still runs in the background with that constant set, as long as the site can send requests to itself, so there’s no need to turn off background processing because of it.
Point the external service at WordPress’s own cron endpoint instead. It is your site address followed by /wp-cron.php?doing_wp_cron, so for a site at example.com the full URL is:
https://example.com/wp-cron.php?doing_wp_cronSubstitute your own domain and request it every 5 to 15 minutes. That single URL covers GravityKit’s background jobs, because they are scheduled through WordPress. A GravityExport Save feed is separate: each feed has its own trigger URL, covered in using FastCron to trigger GravityExport.
