PHP Errors via FastCGI with Nginx on Ubuntu Linode | Solved

Learn how to resolve PHP Errors via FastCGI with Nginx on Ubuntu or Linode. Our Nginx Support team is here to answer the queries and concerns.

PHP Errors via FastCGI with Nginx on Ubuntu Linode | Solved

Running PHP applications on an Ubuntu server using Nginx and FastCGI is a typical setup for hosting dynamic websites.

Unlike Apache, Nginx doesn’t process PHP scripts natively. Instead, it forwards PHP requests to a FastCGI process manager such as PHP-FPM, which executes the code and returns the result to Nginx for client delivery.

Today, we will explore common errors, testing methods, and configuration techniques to get the PHP environment working smoothly with Nginx and FastCGI.

For similar issues like 502 Bad Gateway errors on Linode, you can refer to this troubleshooting guide.

Common Causes of PHP-FPM Errors with Nginx

Although the Nginx and PHP-FPM combo is powerful, misconfigurations can cause blank pages or errors. Here are some frequent culprits:

• Nginx may send the wrong file path to PHP-FPM via the `SCRIPT_FILENAME` parameter. If incorrect, PHP-FPM won’t find the file and will fail silently or return a blank page.
• Nginx or PHP-FPM may not have the necessary permissions to read PHP files or write logs. This can block execution or suppress error logging.
• If PHP error logging or display is disabled in `php.ini` or the PHP-FPM pool config, diagnosing issues becomes difficult.

These issues are not limited to Ubuntu alone — if you’re running PHP-FPM on other distributions like AlmaLinux, you might find this article on AlmaLinux 9 PHP-FPM useful.

How to Fix the Error

Solution 1. Correct Nginx Configuration

The most common fix is to make sure the Nginx configuration sends the correct script path to PHP-FPM. Here are a few best practices:

• Place the `root` directive outside any `location` blocks.
• Turn on `fastcgi_intercept_errors`.
• Increase the verbosity of `error_log`, e.g., to `notice`.
• Review Nginx and PHP-FPM logs for clues.

Solution 2. Break Down and Test Each Component

To troubleshoot effectively, isolate and test each part of the setup and scale up slowly.

1. Use a simple text file to verify that Nginx serves static files correctly.
2. Create `test.txt` in the web root:

   
   echo "Hello world" > /srv/www/mysite.com/public_html/test.txt
   chmod 644 /srv/www/mysite.com/public_html/test.txt
   Copy Code

   Sample server block:

   
   server {
   listen *:80 default;
   server_name mysite.com www.mysite.com;
   root /srv/www/mysite.com/public_html;
   error_log /var/log/nginx/mysite.com/error.log notice;
   access_log /var/log/nginx/mysite.com/access.log main;
   }
   Copy Code
3. Then, test using curl:

   curl --header "Host: mysite.com" 127.0.0.1/test.txtCopy Code

   We will see `Hello world` in the output.
4. Next, place a PHP file in the same directory:

   test.php:

   <?php phpinfo(); ?>
   Copy Code
5. Now, run this command:

   php /srv/www/mysite.com/public_html/test.phpCopy Code

   If this outputs PHP info, PHP itself is working fine.

   Here are some troubleshooting tips:

   • Use the absolute path to PHP if necessary.
   • Set `display_errors = On` and increase `error_reporting` in your `php.ini`.
   • Find the loaded `php.ini` using:

       php -i | grep 'Loaded Configuration'>Copy Code
6. Now, it is time to test PHP-FPM directly via FastCGI. We need the `cgi-fcgi` tool (provided by `libfcgi` on Ubuntu). To install and configure PHP-FPM, here is a sample PHP-FPM pool configuration:

   
   [www]
   listen = 127.0.0.1:9000
   listen.allowed_clients = 127.0.0.1
   pm = dynamic
   pm.max_children = 5
   pm.start_servers = 1
   pm.min_spare_servers = 1
   pm.max_spare_servers = 2
   user = nginx
   group = nginx
   error_log = /var/log/php-fpm.log
   log_level = notice
   Copy Code
7. Then, restart PHP-FPM:

   sudo systemctl restart php-fpmCopy Code
8. Next, run this FastCGI test:

   
   SCRIPT_NAME=/test.php
   SCRIPT_FILENAME=/srv/www/mysite.com/public_html/test.php
   QUERY_STRING=
   REQUEST_METHOD=GET
   cgi-fcgi -bind -connect 127.0.0.1:9000
   Copy Code

   This should return the same PHP info output, this time via FastCGI.

To go deeper into modern server stacks, especially if you’re also using Docker on Linode, this guide on installing Docker might be helpful.

Solution 3. Integrate Nginx with PHP-FPM

To configure Nginx to communicate with PHP-FPM, add a PHP location block in Nginx:

location ~ .php$ {
include /etc/nginx/fastcgi_params;
fastcgi_pass 127.0.0.1:9000;
}
Copy Code

Make sure the `fastcgi_params` file includes:

fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
Copy Code

We may also need:

fastcgi_split_path_info ^(.+.php)(/.+)$;
fastcgi_intercept_errors on;
Copy Code

Here is the final test:

curl --header "Host: mysite.com" 127.0.0.1/test.phpCopy Code

If everything is configured correctly, we will see the output of `phpinfo()`.

If you’re exploring alternative web servers, OpenLiteSpeed on Linode is also a robust and PHP-friendly option worth considering.

[Need assistance with a different issue? Our team is available 24/7.]

Conclusion

Setting up PHP with Nginx and FastCGI on Ubuntu or Linode requires coordination between Nginx, PHP-FPM, and file system permissions. By testing each component independently and using simple diagnostic files, we can identify and fix most configuration issues.

In brief, our Support Experts demonstrated how to resolve PHP Errors via FastCGI with Nginx on Ubuntu or Linode.