Docker-compose Nginx php-fpm file not found

Docker-compose Nginx php-fpm file not found

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

Stefan Bogdanescu

Founder & Senior Architect

Docker Compose Nginx PHP-FPM File Not Found

When you encounter a "Primary script unknown" error in your Nginx and PHP-FPM stack, it almost always points to a mismatch between where Nginx expects to find your files and where they actually reside. This specific issue often stems from how SCRIPT_FILENAME is calculated within the FastCGI configuration.

In the scenario described, the application serves HTML files correctly but returns a 404 for PHP scripts like index.php. The logs reveal that Nginx successfully receives the request and attempts to proxy it to the PHP container (project3-php:9000), but the PHP-FPM process inside the container cannot locate the script.

The root cause lies in the interaction between the host file system, Docker volumes, and the internal paths configured within the containers. Your docker-compose.yml mounts the local html directory to two different locations:

  1. /home/docker in the PHP container (via the volume mount).
  2. /var/www/html in the Nginx container (via the volume mount).

However, your Nginx configuration explicitly sets the root directive to /usr/share/nginx/html, which is the default location for the official Nginx image but not the path where your PHP files are mounted inside the Nginx container. Because the volume mount ./html:/var/www/html happens after the base image layers, your files should be at /var/www/html/index.php.

The critical failure occurs in the location block handling .php requests. You have defined:

fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

By default, Nginx sets $document_root to the value of the root directive, which is /usr/share/nginx/html. Therefore, Nginx constructs a path like /usr/share/nginx/html/index.php.

Inside your PHP container, the volume mount maps the host's html folder to /home/docker. Consequently, the file exists at /home/docker/index.php, not at /usr/share/nginx/html/index.php. When PHP-FPM receives the request for /usr/share/nginx/html/index.php, it looks in that specific path, fails to find a file there, and returns the "Primary script unknown" error.

To resolve this, you must ensure that $document_root points to the actual location of your application code inside the Nginx container. There are two primary ways to achieve this.

Option 1: Update the Nginx Root Directive

The most straightforward fix is to change the root directive in your default.conf to match the volume mount path defined in your docker-compose.yml.

Update your nginxdir/default.conf:

server {
    listen 80;
    server_name localhost;
    index index.php index.html;

    error_log /var/log/nginx/error.log warn;
    access_log /var/log/nginx/access.log;

    # Changed root to match the volume mount path for PHP files
    root /var/www/html; 

    location ~ \.php$ {
        fastcgi_pass project3-php:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        
        # $document_root now resolves to /var/www/html because of the 'root' directive above
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

With this change, Nginx will calculate $document_root as /var/www/html, and SCRIPT_FILENAME will correctly resolve to /var/www/html/index.php. Since your Docker Compose mounts the local html folder to /var/www/html in the Nginx container, the file will be found.

Option 2: Use a Custom Upstream Configuration

If you prefer to keep the standard Nginx image structure or if you are mounting volumes differently, you can explicitly set the document root within the fastcgi_param. However, this is less common and generally harder to maintain if your directory structure changes.

Common Pitfalls to Avoid

When troubleshooting PHP-FPM integration issues, avoid relying solely on links: "project3-php:project3-php" in your Docker Compose file. The links directive primarily updates the /etc/hosts file for DNS resolution within containers; it does not create a network dependency that is required for FastCGI communication. While your current setup uses an explicit IP or hostname (project3-php:9000), relying on implicit linking can sometimes lead to connection refused errors if the PHP container fails to start before Nginx attempts the handshake.

Additionally, ensure that your php.ini configuration allows for external access if you are debugging from outside the Docker network, though for standard internal requests, the default settings are usually sufficient. The primary focus should remain on aligning the root directive with your volume mounts.

For developers looking to streamline this setup further, consider using a dedicated PHP image that includes Nginx or utilizing tools like Laravel Sail if you are building on top of Laravel projects. These tools handle much of the complexity regarding path resolution and environment variables automatically, reducing the likelihood of misconfiguration errors like the one described here.

Our network