Debugging "FastCGI sent in stderr: Primary script unknown": From Log Analysis to Permission Checks

Problem Background and Error Phenomenon

In web server environments based on Nginx and PHP-FPM, developers often encounter the following error message:

FastCGI sent in stderr: "Primary script unknown" while reading response header from upstream...

This error indicates that the FastCGI handler cannot recognize or execute the passed script, but default error logs often lack specific details, making debugging difficult. For example, even with a simple PHP site and basic Nginx setup, the error may suddenly appear, while standard log files (e.g., /var/log/php-fpm/error.log) might have no relevant entries.

Core Debugging Method: Enabling PHP-FPM Access Logs

To obtain more detailed error information, start by configuring PHP-FPM to log access requests. This can be done by modifying PHP-FPM configuration files, with the following steps:

1. Edit the PHP-FPM pool configuration file (typically located at /etc/php-fpm.d/www.conf), add or modify this line:

access.log = /var/log/$pool.access.log

This setting creates a separate access log file for each worker pool, recording all incoming FastCGI requests.

systemctl restart php-fpm

- -  10/Nov/2016:19:02:11 +0000 "GET /app.php" 404

Log Analysis and Problem Diagnosis

By analyzing the access logs, you can quickly pinpoint the specific cause of the error:

• If the log shows a request like "GET /" without a correct PHP filename, this typically indicates an issue with the Nginx configuration. For instance, the fastcgi_param SCRIPT_FILENAME parameter might not be set correctly, causing FastCGI to receive an invalid script path. Check the location ~ \.php$ block in the Nginx configuration to ensure SCRIPT_FILENAME correctly points to the script file under the document root.
• If the log shows a full PHP filename (e.g., "GET /app.php") but returns a 404 status code, the problem may lie in file permissions or path accessibility. The PHP-FPM process (usually running as user php-fpm:php-fpm) might not have permission to read or execute the target PHP file. This can be resolved by checking file ownership and permissions, for example, using chown and chmod commands to adjust them.

Additional Debugging Tips and Configuration Optimization

Beyond access logs, you can enhance debugging capabilities through the following methods:

• Set log_level = notice or a higher level (e.g., debug) in the PHP-FPM configuration to capture more detailed error information. This requires configuration in php-fpm.conf or pool configuration files.
• Enable catch_workers_output = yes to capture the standard output and error streams of worker processes, which helps identify issues during script execution.
• Verify Nginx's FastCGI parameter passing: Ensure the fastcgi_params file includes necessary parameters and that the SCRIPT_FILENAME calculation logic is correct. For example, use $document_root$fastcgi_script_name in the configuration to dynamically build the path.

Conclusion and Best Practices

The key to debugging the "Primary script unknown" error lies in systematically checking logs and configurations. By enabling PHP-FPM access logs, developers can obtain specific request details, distinguishing between Nginx configuration errors and file permission issues. Combining this with other log levels and output capture settings allows for deeper analysis. It is recommended to set up detailed logging in advance when deploying new environments or modifying configurations to quickly address potential problems. Additionally, regularly reviewing file permissions and path settings to ensure PHP-FPM processes have sufficient access rights is an effective measure to prevent such errors.