Nginx 504 gateway timeout with Docker

Nginx 504 gateway timeout with Docker

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

Stefan Bogdanescu

Founder & Senior Architect

Nginx 504 Gateway Timeout with Docker: The Hidden 60-Second Limit

When debugging a 504 Gateway Time-out error in a Dockerized PHP environment, it is easy to assume that increasing timeout values in your configuration files will resolve the issue. However, there is often a hardcoded limit deeper in the system stack that overrides these settings, causing requests to fail after exactly 60 seconds regardless of how you configure Nginx or PHP-FPM.

The scenario described involves a reverse proxy setup where Nginx forwards requests to a PHP application running via FastCGI. The symptoms are specific: the request times out precisely at the 60-second mark, and logs from the backend PHP application confirm that the script is still actively executing and writing output. This behavior strongly suggests that the timeout is not occurring within the application logic but rather at the connection layer between Nginx and the PHP-FPM worker process.

The Default FastCGI Timeout

In standard Linux distributions and many base Docker images, there is a default value for fastcgi_read_timeout in the /etc/nginx/fastcgi_params file. If your custom configuration attempts to set this timeout but fails to include the corresponding directive in the specific location block or if the default file takes precedence, Nginx will terminate the connection after 60 seconds.

This is a common pitfall when debugging Docker containers because base images often ship with fastcgi_read_timeout 60; hardcoded into their default parameter files. Even if your nginx.conf includes a global setting of 300 or 600, you must ensure that the specific location block handling your PHP requests explicitly overrides this default, or that you modify the included fastcgi_params file to remove the hard limit.

Configuration Verification

To resolve this, you need to verify which configuration file is actually being applied. In a Docker container, Nginx typically includes /etc/nginx/fastcgi_params. If your custom nginx.conf does not explicitly redefine fastcgi_read_timeout within the location block that serves your PHP application, the global setting might be ignored in favor of the default included parameters, or the global setting might not apply correctly depending on how the include directive is structured.

Here is a corrected approach for the Nginx configuration:

http {
    # ... other settings ...

    # Explicitly define timeouts in the http block if not already overridden per-location
    fastcgi_read_timeout 300;
    fastcgi_connect_timeout 600;
    fastcgi_send_timeout 600;

    server {
        location /app {
            proxy_pass http://backend;
            
            # Ensure these are set specifically here if using proxy_pass
            proxy_read_timeout 300;
            proxy_connect_timeout 600;
            proxy_send_timeout 600;
        }

        location ~ \.php$ {
            root /var/www/html;
            fastcgi_pass php-fpm:9000;
            
            # This is the critical line often missing in default configs
            fastcgi_read_timeout 300; 
            fastcgi_connect_timeout 600;
            fastcgi_send_timeout 600;

            include fastcgi_params;
        }
    }
}

Note that fastcgi_read_timeout is the directive that controls how long Nginx waits for a response from PHP-FPM. If this is set to the default (or if it remains 60 seconds due to an unmodified default file), increasing proxy_read_timeout on the upstream connection will not help, because the FastCGI protocol handshake itself has timed out.

Docker-Specific Considerations

In a Docker environment, file permissions and volume mounts can sometimes interfere with configuration overrides. If you are mounting your Nginx configuration files from the host into the container, ensure that the mounted nginx.conf or fastcgi_params files actually contain the updated timeout values and that the container is using those specific files rather than falling back to defaults defined in the base image.

Additionally, verify that the PHP-FPM side is not hitting its own internal limits before Nginx times out. While you have already adjusted max_execution_time in php.ini, remember that fastcgi_read_timeout must be greater than or equal to your application's maximum execution time. If your script takes 45 seconds to run but fastcgi_read_timeout is 60, it should work. However, if the default file enforces a strict 60-second cap and your script runs slightly longer, you will see exactly the behavior described in the source material.

Finally, ensure that the proxy_pass directive (if used) does not have its own timeout that conflicts with the FastCGI settings. When using fastcgi_pass, the relevant directives are fastcgi_read_timeout, fastcgi_connect_timeout, and fastcgi_send_timeout. These must be explicitly set in the location block serving PHP requests to guarantee they override any defaults inherited from included parameter files.

Our network