PHP error guide

PHP-FPM Primary script unknown: meaning and fix

error server Affects: Current PHP-FPM, Apache 2.4, or nginx Last verified:

Error summary

Align the web-server document root, fastcgi SCRIPT_FILENAME, and mounted path. FPM cannot map SCRIPT_FILENAME to a readable PHP file.

What it means

Align the web-server document root, fastcgi SCRIPT_FILENAME, and mounted path. FPM cannot map SCRIPT_FILENAME to a readable PHP file.

What the error means

This message means that FPM cannot map SCRIPT_FILENAME to a readable PHP file. The exact signature distinguishes php-fpm primary script unknown from a generic application failure.

Why PHP produces it

The engine or service reports “PHP-FPM Primary script unknown” because its required precondition was not met. Align the web-server document root, fastcgi SCRIPT_FILENAME, and mounted path.

PHP version notes

The php-fpm primary script unknown wording here is based on Current PHP-FPM, Apache 2.4, or nginx; punctuation and exception class names can differ on older branches or vendor builds.

Most common causes

  • The immediate input or configuration reaches the specific condition: FPM cannot map SCRIPT_FILENAME to a readable PHP file
  • The code path assumes the prerequisite for php-fpm primary script unknown has already been satisfied.
  • For php-fpm primary script unknown, development and production differ in version, extension, permissions, paths, or service configuration.
  • An earlier operation returned an unchecked value that is consumed by the line reporting php-fpm primary script unknown.

Minimal examples

BAD — reproduces the problem

nginx 
fastcgi_param SCRIPT_FILENAME /wrong$fastcgi_script_name;

FIXED — safer pattern

nginx 
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

Step-by-step diagnosis

  1. Copy the complete “Primary script unknown” text and retain the first application stack frame.
  2. Reproduce php-fpm primary script unknown in the same SAPI and environment listed for this page.
  3. Before changing php-fpm primary script unknown, inspect the preceding value or directive and verify its type, path, version, and permissions.
  4. Apply the narrow correction—align the web-server document root, fastcgi SCRIPT_FILENAME, and mounted path—then repeat the original request once.

Fixes

Correct the failing prerequisite

Align the web-server document root, fastcgi SCRIPT_FILENAME, and mounted path

nginx 
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

Fail explicitly at the boundary

Validate the condition before the operation that emits php-fpm primary script unknown, and log a safe diagnostic without credentials or full production paths.

Common mistakes when fixing it

  • Suppressing php-fpm primary script unknown instead of correcting its upstream condition.
  • Testing php-fpm primary script unknown only with the CLI binary when the failing request runs under FPM or Apache.
  • Changing a global setting for php-fpm primary script unknown before confirming the site-specific effective configuration.

How to prevent it

  • Add a focused test that exercises the boundary responsible for php-fpm primary script unknown.
  • Keep runtime versions, extensions, configuration, and deploy artifacts affecting php-fpm primary script unknown reproducible.
  • Validate external data and service return values before they can trigger php-fpm primary script unknown.

Web server / environment notes

fpm, linux. The failure occurs where fPM cannot map SCRIPT_FILENAME to a readable PHP file

Tags: fpm,linux

Categories