The right way to fix PHP-FPM 'primary script unknown' issue

Introduction

Many online resources only outline potential causes and solutions for issues related to upgrading PHP versions, leaving users without a clear, step-by-step guide to resolve their problems. This tutorial aims to document the process of upgrading from PHP 8.2 to PHP 8.3 on Amazon Linux 2023 with Nginx, providing a comprehensive guide that can save developers from hours of frustration.

Objective

Objective: Upgrade from PHP 8.2 to PHP 8.3

Server Specs

OS: Amazon Linux 2023  
Server: NGINX 1.26.2

Problem Statement

After upgrading PHP, you may encounter errors in the Nginx error log, such as:

2024/11/09 01:54:40 [error] 3394#3394: *33 FastCGI sent in stderr: "Primary script unknown" while reading response header from upstream, client: 127.0.0.1, server: abc.com, request: "GET /my-api HTTP/1.1", upstream: "fastcgi://unix:/run/php-fpm/www.sock:", host: "abc.com"

This error typically indicates issues with the FastCGI configuration or permissions.

Potential Causes of the Issue

Incorrectly Configured Nginx fastcgi_param Directive

The fastcgi_param directive in your Nginx configuration may not be set correctly. However, since the application was functioning properly before the upgrade, this is likely not the primary cause.

location ~ \.php$ {
    fastcgi_pass    unix:/run/php-fpm/www.sock;
    fastcgi_param   SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include         /etc/nginx/fastcgi_params;
}

Incorrect User Permissions

Given that we just upgraded PHP and PHP-FPM, it's possible that the new PHP-FPM configuration is set to an incorrect user or group. This warrants further investigation.

Debugging Steps

To effectively troubleshoot the issue, follow these steps:

Step 1: Locate the Correct php-fpm.ini Using systemctl

To find the php-fpm.conf, use the following command:

systemctl status php-fpm

This will display output similar to:

ec2-user ~/public_html  01:20:48$ systemctl status php-fpm
● php-fpm.service - The PHP FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php-fpm.service; disabled; preset: disabled)
     Active: active (running) since Sat 2024-11-09 00:44:23 UTC; 1h 5min ago
   Main PID: 3374 (php-fpm)
     Status: "Processes active: 0, idle: 7, Requests: 1, slow: 0, Traffic: 0.00req/sec"
      Tasks: 8 (limit: 4659)
     Memory: 12.3M
        CPU: 304ms
     CGroup: /system.slice/php-fpm.service
             ├─3374 "php-fpm: master process (/etc/php-fpm.conf)"
             ├─3377 "php-fpm: pool www"
             ├─3378 "php-fpm: pool www"
             ├─3379 "php-fpm: pool www"
             ├─3380 "php-fpm: pool www"
             └─3381 "php-fpm: pool www"

From this output, note that it is using /etc/php-fpm.conf.

Step 2: Check the PHP-FPM User Configuration

Open the configuration file:

less /etc/php-fpm.conf

If there is no user setting configured, check for additional configurations in /etc/php-fpm.d/*.conf. Navigate to this directory:

cd /etc/php-fpm.d/
ls

Make a backup of www.conf before editing:

sudo cp www.conf www.conf.bk
sudo vim www.conf

If the file contains:

[www]
user = apache
group = apache

and you’re using NGINX, update user and group to match your NGINX user configuration, typically nginx for both.

After making changes, restart the PHP-FPM service:

systemctl restart php-fpm
systemctl status php-fpm

If everything is configured correctly, your website should be accessible again.

Step 3: Verify User Permissions

If the user and group are correct but issues persist, verify that the user has access to the specified web directory. This is a common issue since users like apache or nginx often lack interactive login capabilities.

To check permissions:

1. Backup your /etc/passwd file:

   cp /etc/passwd /etc/passwd.bk

1. Edit /etc/passwd:

   vim /etc/passwd

1. Change the shell for the user:

nginx:x:992:992:Nginx web server:/var/lib/nginx:/bin/bash

Now switch to the nginx user and check directory access:

su - nginx
cd /path/to/web/directory/

Best Practices

Always Backup Before Upgrading

Take a snapshot backup of your server before performing upgrades. This allows for quick restoration if issues arise during production changes.

Test Upgrades on a Staging Server

Whenever possible, perform upgrades on a staging server before applying them in production environments to mitigate risks.

Conclusion

This guide should help you troubleshoot and fix NGINX’s “Primary script unknown” error following a PHP upgrade, while covering best practices for secure and smooth upgrades.