How to debug "FastCGI sent in stderr: Primary script unknown while reading response header from upstream" and find the actual error message?

How to debug "FastCGI sent in stderr: Primary script unknown while reading response header from upstream" and find the actual error message?

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

How to debug "FastCGI sent in stderr: Primary script unknown" and find the actual error message?

When you see FastCGI sent in stderr: Primary script unknown while reading response header from upstream, the standard advice is often just to check file permissions or ensure the script exists. However, that approach can be frustratingly vague. The error message itself tells us that the FastCGI handler rejected the request, but it frequently fails to tell us why it rejected it. We are left guessing whether it was a missing file, a typo in the path, or a misconfiguration of how the script name is passed to PHP-FPM.

Consider a minimal setup with a simple phpinfo.php and an Nginx configuration that proxies PHP requests to a backend defined as fastcgi_backend. The critical part of this configuration is the fastcgi_param SCRIPT_FILENAME directive:

location ~ \.php$ {
    include /etc/nginx/fastcgi_params;
    fastcgi_pass  fastcgi_backend;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

The problem often lies in how $document_root and $fastcgi_script_name combine. If you request http://testsite.local/phpinfo.php, the variable expansion results in /var/local/mysite/phpinfo.php. If that file does not exist, PHP-FPM logs "Primary script unknown." But what if the file does exist?

This is where the debugging gets interesting. The standard Nginx error logs often only show the upstream rejection, not the actual failure occurring inside the PHP process. This is because, by default, Nginx strips the output stream from the FastCGI process before logging it. You need to explicitly tell PHP-FPM to capture and log its own stderr output.

To achieve this, you must configure catch_workers_output = yes in your PHP-FPM configuration (typically inside www.conf). This setting instructs the master process to read the standard error stream from each worker process and forward it to the Nginx error log. Without this flag, even if your PHP code crashes with a fatal error or an exception, that specific error message will be swallowed by the upstream proxy, leaving you with only the generic "Primary script unknown" notification.

Once catch_workers_output is enabled, the behavior of log_level becomes crucial. Simply setting log_level = notice in php-fpm.conf might not be sufficient if the configuration isn't reloaded or applied to the specific pool file. You must ensure that the catched output is actually being written to a log file you can inspect, such as /var/log/php-fpm/www-error.log.

Here is a practical workflow to isolate the issue:

  1. Verify the catch_workers_output setting: Ensure it is set to yes in your active pool configuration.
  2. Check the Nginx error log: Look for the full stderr dump from PHP-FPM immediately following the "Primary script unknown" message. You should see the actual PHP fatal error, a missing class definition, or a permission denial that triggered the crash.
  3. Inspect SCRIPT_FILENAME: If the logs show the script was found but still failed, verify the exact path constructed by Nginx. Sometimes $document_root is incorrect in your config, pointing to a different directory than where the PHP files actually reside.

There is also a common pitfall involving symlinks or case sensitivity. If your application runs on a Linux filesystem (where file paths are case-sensitive) but you request a file with a different case, the script will not be found even if it exists in a different casing. The "Primary script unknown" error is the upstream's way of saying, "I received a request for this path, and the PHP process confirmed the path is invalid."

If you are using a framework like Laravel or similar modern stacks, ensure your public folder is actually linked to the web root defined in Nginx. A misaligned virtual host configuration can cause Nginx to serve files from /var/www/html while your application code sits in /var/local/mysite. In such scenarios, the SCRIPT_FILENAME parameter will point to a non-existent location.

By enabling catch_workers_output, you turn PHP-FPM into a transparent logger for the upstream failures. This transforms a cryptic nginx error into a readable stack trace or fatal error message, allowing you to debug the root cause rather than just the symptom. If your setup involves complex routing or multiple sites, ensure that fastcgi_param SCRIPT_FILENAME is correctly overridden in every pool to reflect the specific site's document root.

For more advanced configurations involving custom FastCGI handlers or different upstream backends, always verify that the environment variables passed by Nginx match the expectations of your PHP application. While tools like LaravelCompany offer resources for managing complex deployments, understanding these underlying FastCGI mechanics remains essential when dealing with low-level errors.

Our network