Resolving "Primary script unknown" Error in Nginx and PHP Integration

Problem Background and Error Analysis

In the process of deploying Nginx with PHP integration, developers often encounter the "Primary script unknown" error. This error typically appears in the Nginx error log, indicating that the FastCGI process cannot locate the requested PHP script file. From a technical perspective, this is mainly caused by incorrect file path resolution in the Nginx configuration.

Core Configuration Issue Analysis

In the original configuration, the problem lies in the fastcgi_param SCRIPT_FILENAME setting within the location ~ \.php$ block:

fastcgi_param SCRIPT_FILENAME /scripts$fastcgi_script_name;

This configuration has a path mismatch issue. The /scripts path does not match the actual website root directory /usr/share/nginx/html, causing PHP-FPM to be unable to find the script file in the correct location.

Solution Implementation

The correct configuration should point SCRIPT_FILENAME to the actual website root directory:

fastcgi_param SCRIPT_FILENAME /usr/share/nginx/html$fastcgi_script_name;

This modification ensures that PHP-FPM can locate and execute PHP scripts at the correct filesystem location. The $fastcgi_script_name variable in the path automatically includes the requested script filename, combining with the root directory to form the complete file path.

Configuration Optimization Suggestions

In addition to correcting the SCRIPT_FILENAME parameter, a more robust configuration approach can be adopted. Referring to the second answer's suggestion, the root directive can be elevated to the server block level:

server {
    root /usr/share/nginx/html;
    
    location / {
        index index.php;
    }
    
    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

This configuration method uses the $document_root variable, which automatically references the root path defined in the server block, improving configuration maintainability and consistency.

In-depth Understanding of Path Resolution Mechanism

Nginx's path resolution involves multiple components working together. When a request arrives, Nginx first determines the processing rules based on location matching, then forwards the request to PHP-FPM for processing. During this process, the SCRIPT_FILENAME parameter tells PHP-FPM where to look for the script file in the filesystem.

The key point is to ensure that the paths in the Nginx configuration completely match the actual filesystem layout. Any mismatch will result in the "Primary script unknown" error. Developers should carefully check:

• The root directory path in the Nginx configuration
• PHP-FPM process user permissions and file access permissions
• Actual file existence and path accuracy

Debugging and Verification Steps

When encountering such issues, it is recommended to debug according to the following steps:

1. Check the Nginx error log for detailed error information
2. Verify PHP-FPM service status and listening configuration
3. Confirm file permissions and ownership settings
4. Test configuration using absolute paths
5. Gradually simplify configuration to eliminate other interfering factors

Conclusion

The root cause of the "Primary script unknown" error is inconsistent path configuration. By correctly setting the fastcgi_param SCRIPT_FILENAME parameter and adopting a reasonable configuration structure, this problem can be effectively resolved. It is recommended that developers carefully verify all path-related configurations during deployment to ensure coordination and consistency between Nginx, PHP-FPM, and the filesystem.