Skip to main content

Resolving "502 Bad Gateway" on SiteGround: Tuning PHP-FPM & Execution Limits

 Few things induce panic in a backend developer like a sudden "502 Bad Gateway" error during a critical production task. On managed hosting platforms like SiteGround, this scenario is notoriously common when running resource-intensive operations—massive WooCommerce product imports, complex backups, or bulk image regeneration.

The screen goes white, the NGINX error page appears, and your process terminates halfway through. While the immediate symptom is an HTTP error, the root cause lies deep within the interaction between the NGINX reverse proxy, the PHP-FPM process manager, and the strict execution policies enforced on shared and cloud architecture.

This guide details the architectural cause of these timeouts and provides technically rigorous solutions to bypass SiteGround’s hard limits using configuration overrides, WP-CLI, and batch-processing patterns.

Root Cause Analysis: The NGINX/PHP-FPM Handshake

To fix a 502 error, you must understand what generates it. On SiteGround (and most modern stacks), NGINX does not process dynamic PHP content directly. Instead, it acts as a reverse proxy.

Here is the request flow that leads to a crash:

  1. Request: A user initiates a long-running script (e.g., /wp-admin/admin.php?import=products).
  2. Proxy Pass: NGINX receives the request and forwards it to the upstream backend, usually PHP-FPM (FastCGI Process Manager).
  3. Processing: PHP begins executing the logic. This involves heavy I/O, database writes, and memory allocation.
  4. The Timeout: NGINX has a directive called proxy_read_timeout. Simultaneously, PHP-FPM has a request_terminate_timeout.

On shared environments, these are hard-coded—often to 120 seconds or 300 seconds. If your script does not send a response (headers or body) back to NGINX within this window, one of two things happens:

  1. PHP Kills the Script: The FPM process hits its execution limit and self-terminates.
  2. NGINX Gives Up: NGINX gets tired of waiting for the upstream and closes the connection.

In both cases, NGINX receives an invalid response (or an EOF) from the upstream socket. It interprets this as a backend failure and serves the 502 Bad Gateway response to the browser.

Solution 1: Configuration Overrides (The Soft Limits)

Before resorting to architectural changes, we must attempt to maximize the environment constraints accessible to the user. SiteGround allows specific overrides via php.ini (user-level configuration) and .htaccess.

These settings instruct the PHP interpreter to ignore standard defaults, though they cannot override the hard kill signal sent by the master process manager on the server.

1. Creating a Custom php.ini

In your document root (usually public_html), create or edit the php.ini file. Add the following directives to maximize resource allocation:

; Increase maximum execution time (seconds)
; Attempting to set this to -1 (infinite) is often blocked, 
; so set a high specific number.
max_execution_time = 600
max_input_time = 600

; Increase memory limit to handle large data sets
memory_limit = 512M

; Ensure huge post data (like XML imports) isn't truncated
post_max_size = 128M
upload_max_filesize = 128M

2. Modifying .htaccess

Next, instruct the web server to respect these timeouts. Add these lines to the top of your .htaccess file:

<IfModule mod_php7.c>
    php_value max_execution_time 600
    php_value max_input_time 600
    php_value memory_limit 512M
</IfModule>

# If using lsapi (LiteSpeed/SiteGround Ultrafast PHP)
<IfModule lsapi_module>
    php_value max_execution_time 600
    php_value max_input_time 600
</IfModule>

Note: If the 502 persists after applying these changes, the task is hitting the hard server-level timeout defined in the global FPM pool configuration, which you cannot edit on shared hosting. You must move to Solution 2.

Solution 2: Bypassing HTTP Timeouts with WP-CLI (The Real Fix)

The most effective way to resolve 502 errors for heavy tasks is to stop running them over HTTP.

HTTP requests are subject to NGINX timeouts. SSH and CLI (Command Line Interface) processes are not. By executing your import or backup via the terminal, you bypass the web server entirely, interacting directly with the PHP SAPI (Server API).

Step 1: Connect via SSH

Access your SiteGround server via a terminal:

ssh user@siteground-ip-address -p 18765

Step 2: execute Tasks via WP-CLI

If you are running a WooCommerce import or a database operation, use WP-CLI. This tool runs PHP in CLI mode, which typically has an infinite execution timeout by default.

Example: Running the WP All Import plugin via CLI

Instead of clicking "Run Import" in the browser:

# Navigate to public root
cd public_html

# List available imports
wp all-import list

# Run the specific import ID (e.g., ID 5)
# This will run until completion without a 502 error
wp all-import run 5

Example: Regenerating Thumbnails

# Regenerate all thumbnails without browser timeouts
wp media regenerate --yes

This is the definitive solution for backend engineers. It shifts the workload from the fragile HTTP layer to the robust system layer.

Solution 3: Batch Processing in Custom Code

If you are writing the custom script causing the 502 (e.g., a custom API sync), and you cannot use SSH, you must implement Batch Processing.

You cannot load 10,000 records into memory and process them in a single loop. You must break the execution into chunks and reload the page (AJAX or HTTP redirects) to reset the execution timer.

Below is a modern PHP implementation utilizing microtime to self-regulate execution duration.

<?php

declare(strict_types=1);

namespace App\Services;

class BatchImporter
{
    // Safety buffer: Stop 5 seconds before the likely 120s limit
    private const TIME_LIMIT_SECONDS = 115;
    private float $startTime;

    public function __construct()
    {
        $this->startTime = microtime(true);
    }

    public function processItems(array $items): array
    {
        $processedCount = 0;
        $status = 'completed';
        $lastProcessedIndex = 0;

        foreach ($items as $index => $item) {
            // Check if we are approaching the timeout
            if ($this->shouldStopExecution()) {
                $status = 'partial';
                $lastProcessedIndex = $index;
                break;
            }

            $this->heavyOperation($item);
            $processedCount++;
        }

        return [
            'status' => $status,
            'processed_count' => $processedCount,
            'next_offset' => $lastProcessedIndex,
        ];
    }

    private function shouldStopExecution(): bool
    {
        $elapsed = microtime(true) - $this->startTime;
        return $elapsed >= self::TIME_LIMIT_SECONDS;
    }

    private function heavyOperation(mixed $item): void
    {
        // Simulate DB writes or Image processing
        usleep(50000); // 50ms per item
    }
}

How to Consume This

Your frontend (React/Vue/jQuery) should call this endpoint. If the response returns status: 'partial', the frontend immediately fires a new request passing the next_offset. This creates a chain of short requests (e.g., 20 seconds each) that never trigger the NGINX 502 timeout.

Deep Dive: SAPI Differences (CLI vs. FPM)

Why does the CLI method work when the config changes fail? It comes down to the SAPI (Server API).

  1. FPM (FastCGI Process Manager): Designed for web requests. It has strict safeguards to prevent one process from hogging the CPU and starving other incoming web traffic. It assumes that if a web page takes 300 seconds to load, something is broken.
  2. CLI (Command Line Interface): Designed for system tasks. It defaults to max_execution_time = 0 (infinite). It assumes the operator knows what they are doing and will manually kill the process if it hangs.

On SiteGround’s "Ultrafast PHP" (based on NGINX + PHP-FPM), the FPM pool config is locked down. However, the CLI environment operates outside this pool, sharing the same file system and database access but ignoring the web-server timeout rules.

Common Pitfalls and Edge Cases

1. The Database "Wait Timeout"

Even if you solve the PHP timeout, you might hit a MySQL error: MySQL server has gone away. This happens if your PHP script stays alive (via CLI) but the connection to the database sits idle for too long between queries.

  • Fix: Ensure your script reconnects to the database if the connection is lost, or increase wait_timeout in your MySQL variables if possible.

2. Memory Leaks in Long Loops

When processing thousands of items in a single PHP-CLI process, PHP’s Garbage Collector (GC) may not clear memory fast enough.

  • Fix: Manually trigger garbage collection inside your loop if you notice RAM usage spiking.
// Inside your heavy loop
if ($iteration % 100 === 0) {
    gc_collect_cycles();
}

3. "Ultrafast PHP" vs Standard

SiteGround offers "Ultrafast PHP" on higher-tier plans. This setup is more aggressive with timeouts than Standard PHP. If you cannot use CLI and batching is difficult, temporarily switching the site to Standard PHP in the SiteGround Site Tools dashboard can sometimes relax the strict FPM constraints, allowing a slightly longer execution window.

Conclusion

The "502 Bad Gateway" on SiteGround is rarely a server crash; it is a feature designed to maintain stability on shared architecture. While increasing php.ini limits is the first line of defense, it is often insufficient for heavy workloads.

For backend developers and administrators, shifting execution context from HTTP to WP-CLI/SSH is the only guaranteed method to bypass these hard limits. For custom application logic, implementing time-aware batch processing ensures your application remains resilient regardless of the hosting environment's constraints.

Labels: