Have you ever experienced an irritating NGINX server “504 Gateway Timeout” error? Most likely, the problem stems from a badly specified timeout setting. NGINX employs a range of timeout mechanisms to regulate server-client communication, guaranteeing effective resource distribution and mitigating incessant queries. But understanding and modifying these might be scary.
This knowledgebase explains details about these timeouts and their solutions along with their purpose, configuration options, and safe disablement techniques. To solve the problem quickly and easily, follow the instructions in the knowledge base:
Identify the Cause
First, confirm that the 504 error is due to a timeout issue. Check your NGINX error logs (usually located at /var/log/nginx/error.log) for messages indicating a timeout.
tail -n 50 /var/log/nginx/error.logIf the log entry resembles this: upstream timed out (110: Connection timed out) while connecting to upstream, It means NGINX couldn’t get a response from the upstream server within the specified timeout period and this can be solved by altering the values in NGINX configuration.
To begin with, familiarize yourself with the distinctions among the values that can be altered in the Nginx configuration file: /etc/nginx/sites-available/default or /etc/nginx/nginx.conf, which is required to fix the timeout problem:
| Setting | Purpose | Default Value | Modification Example | Example Scenario |
|---|---|---|---|---|
| keepalive_timeout | Duration a connection remains idle before NGINX closes it. | 65s | keepalive_timeout 30; | Useful for websites with frequent client requests, to free up server connections quickly. |
| send_timeout | Maximum time allowed for NGINX to send a response to the client. | 60s | send_timeout 120; | Beneficial for servers handling large files or media streaming, to accommodate slower client speeds. |
| proxy_read_timeout | Determines how long NGINX will wait for a response from a proxied server. | 60s | proxy_read_timeout 180s; | Helpful for backends performing time-consuming operations like report generation. |
| proxy_connect_timeout | Sets the maximum time NGINX will wait while establishing a connection with an upstream server. | 60s | proxy_connect_timeout 90s; | Useful when upstream servers are under heavy load and take longer to establish connections. |
| fastcgi_read_timeout | Specifies how long NGINX will wait for a response from a FastCGI process, like PHP-FPM. | 60s | fastcgi_read_timeout 300s; | Ideal for hosting complex PHP applications requiring longer processing times. |
Now let’s get to the core of modifying each timeout setting:
Open your NGINX configuration file for editing. This file is typically found at /etc/nginx/nginx.conf or in the sites-enabled directory within /etc/nginx/. If you have a specific configuration for your site, it might be in a file named after your domain in the sites-available directory and symlinked to sites-enabled.
vi /etc/nginx/sites-available/defaultOR
vi /etc/nginx/nginx.confThen, Find the location block in your configuration that is handling the requests for the large files. It will look something like this:
location /path/to/large/files/ {
…
}Inside this block, add or modify the desired directive.
For example; if you’re facing the error after serving very large files, you might need to increase proxy_read_timeout to several minutes.
Example of the error:
2024/01/10 15:48:00 [error] 6545#6545: *12345 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 192.168.1.100, server: example.com, request: "GET /some-resource HTTP/1.1", upstream: "http://upstream-server:port/some-resource", host: "example.com"
Example of edit:
location /path/to/large/files/ {
…
proxy_read_timeout 300s; # Sets the timeout to 5 minutes
…
}The other error examples in the error.log file along with the values you can adjust to fix the problem are as follows, for your reference:
keepalive_timeout
Log Entry Example:
*1 client stopped connection before send body completed while sending to client, client: 192.168.1.100, server: example.com, request: "GET / HTTP/1.1", host: "example.com"
Indicates: The client closed the connection before NGINX was able to complete sending the response. This could be because the keepalive_timeout duration was exceeded.
fastcgi_read_timeout
Log Entry Example:
upstream timed out (110: Connection timed out) while reading response header from upstream, client: 192.168.1.100, server: example.com, request: "GET /php-app.php HTTP/1.1", upstream: "fastcgi://127.0.0.1:9000", host: "example.com"
Indicates: NGINX did not receive a response from the FastCGI process (like PHP-FPM) within the specified fastcgi_read_timeout. This could suggest the PHP process is taking too long to execute or is stuck.
proxy_connect_timeout
Log Entry Example:
connect() timed out (110: Connection timed out) while connecting to upstream, client: 192.168.1.100, server: example.com, request: "GET /app HTTP/1.1", upstream: "http://127.0.0.1:8080", host: "example.com"
Indicates: NGINX was unable to establish a connection with the upstream server within the proxy_connect_timeout. This is often a network-related issue or the upstream server is not accepting connections.
send_timeout
Log Entry Example:
*1 client timed out (110: Connection timed out) while sending response to client, client: 192.168.1.100, server: example.com, request: "GET /large-file.zip HTTP/1.1", host: "example.com"
Indicates: NGINX was unable to send data to the client within the send_timeout period. This could occur if the client is reading data too slowly, often due to network issues on the client’s side or the client has stopped receiving data without properly closing the connection.
These are typical examples of timeout-related errors you might encounter in the NGINX error log. When you see these, you usually start troubleshooting by looking at the respective timeout settings in your NGINX configuration and considering adjustments based on the context of the error.
