CRITICAL

How to Fix Nginx AH01071: Got error 'Primary script unknown' (PHP-FPM 2026)

Quick Fix Summary

TL;DR

Verify the `fastcgi_param SCRIPT_FILENAME` directive in your Nginx location block points to the correct, accessible PHP file path.

Nginx's FastCGI module cannot locate the PHP file specified in the `SCRIPT_FILENAME` parameter to pass to PHP-FPM. This is a critical path or permission mismatch between the web server and the PHP processor.

Diagnosis & Causes

  • Incorrect `SCRIPT_FILENAME` path in Nginx config.
  • File or directory permission issues (www-data/user mismatch).
  • PHP-FPM pool `chroot` or `chdir` settings misconfigured.
  • Symbolic link traversal is disabled (`disable_symlinks`).
  • The requested `.php` file does not exist on the server.

    • Recovery Steps

    1

    Step 1: Validate Nginx `fastcgi_param` Configuration

    The most common cause is a missing or incorrect `SCRIPT_FILENAME`. Ensure it uses `$document_root$fastcgi_script_name`.

    bash 
    # Check your Nginx site config
grep -A5 -B5 'location ~ \.php$' /etc/nginx/sites-available/your_site
# Correct configuration inside location block:
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
    2

    Step 2: Verify File Permissions and Ownership

    Nginx/PHP-FPM workers must have read (and execute for directories) permissions on the PHP file and its path.

    bash 
    # Check ownership and permissions of the target file and its parent directories
ls -la /path/to/your/php/file.php
ls -la /path/to/your/php/
# Typical fix: Set correct ownership (adjust user:group for your OS, e.g., www-data:www-data)
sudo chown -R www-data:www-data /var/www/your_site/
sudo chmod -R 755 /var/www/your_site/
    3

    Step 3: Inspect PHP-FPM Pool Configuration

    Misaligned `chroot`, `chdir`, or user/group settings in the PHP-FPM pool can break file path resolution.

    bash 
    # Locate and check your active PHP-FPM pool (e.g., www.conf)
sudo nano /etc/php/8.3/fpm/pool.d/www.conf
# Key directives to verify:
user = www-data
group = www-data
listen.owner = www-data
listen.group = www-data
;chroot =
;chdir = /var/www
    4

    Step 4: Test PHP-FPM Script Access Directly

    Use `sudo -u` to test if the PHP-FPM worker user can actually read the file, isolating Nginx from the equation.

    bash 
    # Test as the PHP-FPM user (e.g., www-data)
sudo -u www-data cat /var/www/your_site/public/index.php
# If this fails, it's a definitive permission/ownership issue.
# Also check if open_basedir restrictions in php.ini are blocking access.
    5

    Step 5: Check for SELinux/AppArmor Context Issues (Linux)

    Mandatory Access Control systems can block Nginx/PHP-FPM from accessing files, even with correct POSIX permissions.

    bash 
    # For SELinux (RHEL/CentOS/Fedora): Check and adjust context
ls -Z /var/www/your_site/
sudo chcon -R -t httpd_sys_content_t /var/www/your_site/
# For AppArmor (Ubuntu/Debian): Ensure Nginx/PHP-FPM profiles are in complain mode or properly configured.
sudo aa-status | grep -E '(nginx|php-fpm)'
    6

    Step 6: Analyze Nginx & PHP-FPM Logs for Specifics

    Logs provide the exact path PHP-FPM received and the error context. Always check them first in production.

    bash 
    # Tail Nginx error log for AH01071
sudo tail -f /var/log/nginx/error.log
# Tail PHP-FPM slow log or error log for corresponding entries
sudo tail -f /var/log/php8.3-fpm.log
# The log will show the exact 'Primary script unknown' path PHP-FPM tried to access.

    Architect's Pro Tip

    "In containerized environments (Docker/K8s), this error often stems from volume mount paths. The path inside the Nginx container must match the path the PHP-FPM container expects. Use `docker exec` to `cat` the file from both containers."

    Frequently Asked Questions

    My config looks correct and permissions are right, but I still get AH01071. What's next?

    Check if you have multiple `fastcgi_param SCRIPT_FILENAME` directives. The last one wins. Also, verify `$document_root` is correctly set by the `root` directive in your server or location block.

    Does this error mean PHP-FPM is not running?

    No. If PHP-FPM was down, Nginx would return a 502 Bad Gateway error. AH01071 specifically means the connection works, but PHP-FPM cannot find the script file at the given path.

    Should I use `$request_filename` instead of `$document_root$fastcgi_script_name`?

    In standard setups, `$document_root$fastcgi_script_name` is more reliable. `$request_filename` can sometimes include incorrect paths, especially with complex rewrites or aliases.

    Related Nginx Guides

    SSL_do_handshake() failed (SSL: error:0A000126:SSL routines::unexpected eof while reading)

    How to Fix Nginx SSL Handshake EOF Error in 2025
    SSL_do_handshake() failed

    How to Fix Nginx SSL Handshake Failed (SSL_do_handshake) in 2025
    502

    How to Fix Nginx 502