How to Fix 502 Error: PHP-FPM Socket Issues in PHP/Laravel Forge

Let’s jump straight into it.

The fix for your 502 error in Laravel Forge: Navigate to your server dashboard, click on the dropdown menu next to your PHP version, and click the Restart button. This reloads PHP-FPM (FastCGI Process Manager) and recreates the missing Unix socket.

Alternatively, or if you’re using vanilla PHP, you can SSH into your server and manually reload PHP-FPM with the command sudo service php8.x-fpm restart (replace 8.x with your PHP version, e.g., php8.4-fpm). This recreates the missing Unix socket that Nginx needs to communicate with PHP-FPM, resolving the 502 error immediately.

Understanding the 502 Error: What Causes PHP-FPM Connection Failures

A 502 error (also called a 502 Bad Gateway error) occurs when Nginx, your web server, cannot successfully communicate with PHP-FPM, the service responsible for processing PHP requests.

This PHP-FPM connection breakdown typically happens in one of these scenarios:

• The PHP-FPM service has stopped or crashed.
• The PHP-FPM Unix socket file is missing or inaccessible.
• PHP-FPM is misconfigured or experiencing issues.
• Server resources are exhausted, causing PHP-FPM to fail (if you haven’t changed any configurations, this is the 502’s most likely cause, not the missing Unix socket file).

In Laravel Forge environments, Nginx is configured to pass PHP requests to PHP-FPM through a Unix socket located at /var/run/php/phpX.X-fpm.sock. When this socket file doesn't exist or isn't accessible, Nginx returns a 502 error because it has nowhere to forward the PHP processing requests. This is a very common cause of 502 errors.

Another scenario we see often is:

1. A user changes the Nginx configuration for a site, but doesn’t change it correctly. This prevents Nginx from restarting (or will cause issues while doing so).
2. A user adds a new site or tries to update their PHP version (from 8.3 to 8.4, for example) for that site.
3. Nginx will automatically try to restart when you update the PHP version, but it won't be able to because a site (any site on that server) has introduced an Nginx configuration error.
4. In this case, the socket is likely missing.

How It Works: Nginx, PHP-FPM, and the 502 Error Connection Flow

Understanding the relationship between Nginx and PHP-FPM helps diagnose and prevent future issues:

1. Normal Request Flow

When a visitor accesses your Laravel application:

• Nginx receives the HTTP request
• For PHP files, Nginx forwards the request to PHP-FPM via the Unix socket
• PHP-FPM processes the PHP code
• The response travels back through the socket to Nginx
• Nginx delivers the final response to the visitor

2. Unix Socket Communication

Laravel Forge configures Nginx to communicate with PHP-FPM using Unix sockets rather than TCP connections. Each PHP version installed on your server runs its own FPM process with its own socket:

• PHP 8.4: /var/run/php/php8.4-fpm.sock
• PHP 8.3: /var/run/php/php8.3-fpm.sock
• PHP 8.2: /var/run/php/php8.2-fpm.sock

3. What Happens When PHP-FPM Stops

When PHP-FPM stops running:

• The socket file is automatically removed from the filesystem
• Nginx attempts to connect to a non-existent socket
• The connection fails, triggering the 502 error
• Your website becomes inaccessible until PHP-FPM restarts

4. Multiple PHP Versions on Forge

Laravel Forge supports running multiple PHP versions simultaneously. Each version operates independently with its own FPM process. This means a 502 error will only affect sites using the specific PHP version whose FPM service has stopped.

Integration: Laravel Forge Deployment Scripts

To prevent 502 errors after deployments, especially when using OPcache optimization, you should integrate PHP-FPM restarts into your deployment workflow.

Adding PHP-FPM Restart to Deployment Scripts

If you’ve enabled zero-downtime deployments in Laravel Forge for your new sites, you don’t have to restart PHP-FPM during deployments.

If you haven’t enabled it, Laravel Forge provides environment variables that make it easy to restart the correct PHP-FPM service automatically. In your site's deployment script, add this command at the end:

1sudo -S service $FORGE_PHP_FPM reload

Or for a full restart:

1sudo -S service $FORGE_PHP_FPM restart

The $FORGE_PHP_FPM variable automatically references the correct PHP-FPM process name for your site's PHP version, so you don't need to hardcode version numbers.

Complete Deployment Script Example

 1cd /home/forge/example.com
 2git pull origin $FORGE_SITE_BRANCH
 3 
 4$FORGE_COMPOSER install --no-interaction --prefer-dist --optimize-autoloader
 5 
 6touch /tmp/fpmlock 2>/dev/null || true
 7( flock -w 10 9 || exit 1
 8    echo 'Reloading FPM...'; sudo -S service $FORGE_PHP_FPM reload ) 9>/tmp/fpmlock
 9 
10if [ -f artisan ]; then
11    $FORGE_PHP artisan migrate --force
12    $FORGE_PHP artisan optimize
13fi

Why Restart PHP-FPM During Deployments?

When you have OPcache enabled (recommended for production), PHP caches compiled code in memory for better performance.

However, this means that after deploying new code, PHP-FPM may continue serving old cached versions until the cache is cleared. Restarting or reloading PHP-FPM ensures:

• OPcache is cleared
• New code changes take effect immediately
• No stale cached code is served to users

Examples: Troubleshooting and Resolution Steps

Example 1: Quick Fix for 502 Error Using Laravel Forge Dashboard

Scenario: Your site suddenly shows a 502 error, and you need an immediate fix through Laravel Forge.

Solution:

1. Log into your Laravel Forge account at forge.laravel.com
2. Navigate to your server
3. Click on the PHP tab in the left sidebar
4. Locate your PHP version (e.g., PHP 8.4)
5. Click the Restart button next to that PHP version
6. Wait 10-15 seconds for PHP-FPM to restart
7. Refresh your site to verify the 502 error is resolved
8. If the 502 error isn’t resolved, check if you’ve made any recent changes to your PHP or Nginx configuration. If you have, try to revert them, and see if it works.

Example 2: Quick Fix for 502 Error via SSH

Scenario: Your site suddenly shows a 502 error, and you need an immediate fix via the command line.

Solution:

1. SSH into your server: ssh forge@your-server-ip.

2. Check which PHP version your site uses (visible in Forge dashboard under Site > Meta).

3. Restart the PHP-FPM service:

   1sudo service php8.4-fpm restart
   

4. Verify the service is running:

   1sudo service php8.4-fpm status
   

5. Check that your site loads correctly and the 502 error is gone.

Example 3: Verifying PHP-FPM Socket Exists

Scenario: You want to confirm whether the socket file exists before restarting services.

Solution:

 1# List all PHP-FPM sockets
 2ls -la /var/run/php/
 3 
 4# Check if your specific version's socket exists
 5ls -la /var/run/php/php8.4-fpm.sock
 6 
 7# If the socket is missing (causing the 502 error), restart PHP-FPM
 8sudo service php8.4-fpm restart
 9 
10# Verify the socket was recreated
11ls -la /var/run/php/php8.4-fpm.sock

Example 4: Checking PHP-FPM Error Logs to Diagnose 502 Errors

Scenario: PHP-FPM keeps stopping, and you need to identify the root cause.

Solution:

1# View recent PHP-FPM errors for your PHP version
2sudo tail -f /var/log/php8.4-fpm.log
3 
4# Check system logs for more context
5sudo journalctl -u php8.4-fpm -n 50

Common issues revealed in logs:

• Permission errors (check file ownership and socket permissions)
• Configuration syntax errors (review recent config changes)

Example 5: Switching PHP Versions in Laravel Forge After 502 Errors

Scenario: After updating PHP versions on Forge, your site shows 502 errors because it's trying to use the wrong PHP-FPM version.

Solution:

1. In the Forge dashboard, navigate to your site.
2. Go to Settings in the top nav and then look for PHP version.
3. Change the PHP version to the newly installed version in the dropdown menu.
4. Forge automatically updates the Nginx configuration and PHP-FPM settings.
5. Redeploy your website to ensure all services sync properly and the 502 error is resolved.

Related Concepts

PHP-FPM Process Management

PHP-FPM uses process pools to handle requests efficiently. Understanding the configuration can help prevent 502 errors:

• pm.max_children: Maximum number of child processes or the number of requests that can be handled simultaneously at any given moment.
• pm.start_servers: Number of processes started initially; the figure must be between pm.min_spare_servers and pm.max_spare_servers.
  • Formula: pm.min_spare_servers ≤ pm.start_servers ≤ pm.max_spare_servers
• pm.min_spare_servers: Minimum idle processes; must be less than pm.max_spare_servers.
• pm.max_spare_servers: Maximum idle processes; must be less than or equal to pm.max_children.
  • Formula: pm.max_spare_servers ≤ pm.max_children

The Complete Hierarchy:

pm.min_spare_servers ≤ pm.start_servers ≤ pm.max_spare_servers ≤ pm.max_children

Example of a Valid Configuration:

pm = dynamic pm.max_children = 50 pm.start_servers = 10 pm.min_spare_servers = 5 pm.max_spare_servers = 15

In this example: 5 ≤ 10 ≤ 15 ≤ 50 ✓ If you violate these rules, PHP-FPM will typically refuse to start and give you an error message indicating which constraint was violated.

If your server receives more concurrent requests than pm.max_children allows, users may experience 502 errors during traffic spikes.

OPcache and Deployment Best Practices

OPcache improves PHP performance by storing OPcodes in shared memory. On production servers with OPcache enabled, always reload PHP-FPM after deployments to ensure code changes take effect.

Unix Sockets vs. TCP Connections

Laravel Forge uses Unix sockets for PHP-FPM communication because they're faster and more secure than TCP connections for local communication. However, Unix sockets are file-system-based, making them vulnerable to deletion if PHP-FPM crashes or stops improperly.

Multiple PHP Version Management

Laravel Forge excels at managing multiple PHP versions on a single server and simplifies the installation and update processes. Each version operates independently, so issues with one version don't affect sites running other versions. This isolation is crucial for:

• Testing applications on newer PHP versions
• Maintaining legacy applications on older PHP versions
• Running multiple projects with different requirements

Nginx Configuration and FastCGI

Your site's Nginx configuration file (located at /etc/nginx/sites-available/your-site) contains the FastCGI parameters that tell Nginx how to communicate with PHP-FPM. Laravel Forge automatically manages these configurations when you change PHP versions through the dashboard.

Note: We don’t recommend manually editing fastcgi_variables in your Nginx configuration, as this can lead to 502 errors that won’t be resolved by restarting.

Server Resource Monitoring

502 errors can also indicate resource constraints. Monitor:

• Available memory (PHP-FPM can crash from memory exhaustion)
• Disk space (full disks prevent socket creation)
• CPU usage (excessive load can cause timeouts)
• Open file limits (too many connections can exhaust file descriptors)

You can easily monitor server and email metrics using Laravel Forge.

Conclusion: Resolving 502 Error and PHP-FPM Issues in Forge

The 502 error caused by missing PHP-FPM sockets is typically quick to resolve with a simple service restart through Laravel Forge's dashboard or via SSH.

However, understanding the underlying communication between Nginx and PHP-FPM helps you diagnose recurring 502 errors, optimize your deployment workflow, and maintain a stable production environment.

For Laravel Forge users, monitoring server resources such as CPU load average, used disk space, and memory can help prevent 502 errors.

Plus, leveraging built-in environment variables like $FORGE_PHP_FPM in deployment scripts ensures your PHP-FPM service stays synchronized with your code deployments, reducing the likelihood of 502 errors affecting your users.

Remember: most 502 error instances related to PHP-FPM can be resolved in under a minute using the Forge dashboard's PHP restart functionality.