Web Services

Common PHP-FPM Errors and How to Fix Them

Learn how to troubleshoot common PHP-FPM errors, such as 502 Bad Gateway, memory leaks, and socket issues. Follow this guide to resolve PHP-FPM issues quickly and improve your server's performance.

PHP-FPM (FastCGI Process Manager) is essential for running PHP applications efficiently, especially in high-traffic environments. However, like any server-side process, PHP-FPM can encounter errors that affect the performance and stability of your web applications. Understanding these common issues and knowing how to resolve them is critical to maintaining a robust PHP environment. In this guide, we will discuss some of the most frequent PHP-FPM errors and provide step-by-step instructions on how to fix them.

1. 502 Bad Gateway Error

What Causes It?

One of the most common errors related to PHP-FPM is the dreaded 502 Bad Gateway. This usually happens when your web server (like NGINX or Apache) fails to communicate with the PHP-FPM backend. This can be caused by several factors such as:

  • PHP-FPM not running or crashing.
  • Incorrect FastCGI settings in the web server configuration.
  • PHP-FPM running out of resources like memory or process limits.

How to Fix It:

Increase resource limits: If PHP-FPM is running out of resources, you might need to increase the pm.max_children value in the PHP-FPM configuration to allow more processes.

pm.max_children = 20

Check PHP-FPM logs: PHP-FPM logs can give clues as to what might be going wrong. Check the logs for any error messages:

sudo tail -f /var/log/php7.4-fpm.log

Inspect the NGINX or Apache configuration: Ensure the FastCGI socket or port settings are correct in your web server configuration. For example, in an NGINX config file:

location ~ \.php$ {
    fastcgi_pass unix:/run/php/php7.4-fpm.sock;
    fastcgi_index index.php;
    include fastcgi_params;
}

Check if PHP-FPM is running: Use the following command to see if PHP-FPM is active.

sudo systemctl status php-fpm

If PHP-FPM is not running, start it with:

sudo systemctl start php-fpm

2. "Primary Script Unknown" Error

What Causes It?

The "Primary script unknown" error typically occurs when PHP-FPM is unable to find the PHP file requested by the web server. This often happens due to incorrect file paths in the server’s FastCGI configuration or insufficient permissions on the PHP files.

How to Fix It:

Check file permissions: Ensure the PHP files and directories have the correct permissions and that the PHP-FPM user (e.g., www-data) has access to them.

sudo chown -R www-data:www-data /path/to/your/php/files
sudo chmod -R 755 /path/to/your/php/files

Verify the file path: Ensure that the web server's FastCGI settings point to the correct directory where your PHP files are located. For NGINX:

fastcgi_param SCRIPT_FILENAME /path/to/your/php/files$fastcgi_script_name;

3. PHP-FPM Memory Leaks

What Causes It?

Memory leaks in PHP-FPM can cause excessive memory consumption, leading to server crashes or degraded performance. This typically happens when PHP scripts are not properly releasing memory after execution or when PHP-FPM child processes handle too many requests without being recycled.

How to Fix It:

  • Use debugging tools: Tools like Xdebug or New Relic can help you monitor memory usage and detect potential memory leaks in your PHP code.

Check memory limits: You can also set memory limits on PHP processes by configuring memory_limit in your PHP configuration.

memory_limit = 128M

Enable process recycling: Use the pm.max_requests directive to limit the number of requests each child process can handle before it’s killed and restarted. This helps free up memory.

pm.max_requests = 500

4. Socket File Not Found

What Causes It?

When PHP-FPM is set to use a Unix socket for communication with the web server (e.g., /run/php/php7.4-fpm.sock), errors can occur if the socket file is missing or the web server does not have the proper permissions to access it.

How to Fix It:

Switch to TCP if necessary: If socket issues persist, consider switching to TCP communication by changing the listen directive in PHP-FPM to a TCP port.

listen = 127.0.0.1:9000

Check socket permissions: Make sure the socket file has the correct permissions for the web server user to access it.

sudo chmod 666 /run/php/php7.4-fpm.sock

Ensure PHP-FPM is configured to use the correct socket path: In your PHP-FPM pool configuration, verify the socket path.

listen = /run/php/php7.4-fpm.sock

5. "Server Reached Max Children" Error

What Causes It?

This error occurs when PHP-FPM has reached its maximum number of child processes. If this happens frequently, it means that your server is handling more requests than PHP-FPM is configured to manage.

How to Fix It:

  • Optimize your server: If increasing the number of child processes doesn’t solve the issue, you might need to scale your server horizontally or optimize your PHP code to reduce resource usage.

Increase pm.max_children: Adjust the pm.max_children setting in your PHP-FPM configuration to allow more child processes, depending on your server's resources.

pm.max_children = 30

PHP-FPM is a powerful tool that significantly improves the performance and scalability of PHP applications, but it’s not without its challenges. Common errors like 502 Bad Gateway, Primary Script Unknown, and memory leaks can be frustrating, but with the right troubleshooting steps, they can be resolved quickly. By understanding these errors and how to fix them, you can ensure a smoother and more stable PHP environment.

Read more