Nginx proxy_read_timeout Explained: Configuration, 504 Gateway Timeout, and Best Practices

Introduction

The proxy_read_timeout directive specifies how long Nginx waits to receive a response from an upstream server after forwarding a request.

When Nginx is configured as a reverse proxy, backend services such as Node.js, Java, Go, Python, ASP.NET, or containerized applications process client requests. If the upstream server does not send any data within the configured timeout period, Nginx closes the connection and returns a 504 Gateway Timeout error.

Understanding this directive is essential for applications that rely on reverse proxy architectures, load balancing, or microservices.

This guide explains how proxy_read_timeout works, how to configure it, recommended values, and common configuration mistakes.

Test Environment

Operating System : AlmaLinux 10
PHP Version      : PHP 8.3
Web Server       : Nginx
PHP-FPM          : Enabled
Architecture     : x86_64
Last Tested      : July 2026

What Is proxy_read_timeout?

The proxy_read_timeout directive determines how long Nginx waits for the upstream server to send data.

Example:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_read_timeout 60s;
}

In this example, Nginx waits up to 60 seconds for the backend server to begin sending a response.

If no data is received within that period, Nginx terminates the request.

How It Works

Browser
    │
    ▼
Nginx
    │
    ▼
Reverse Proxy
    │
    ▼
Backend Server
(Node.js / Java / Go / Python)
    │
    ├── Response Within Timeout
    │         │
    │         ▼
    │     Return Response
    │
    └── No Response
              │
              ▼
     504 Gateway Timeout

Unlike fastcgi_read_timeout, this directive applies to proxy_pass connections rather than FastCGI.

Where Is proxy_read_timeout Configured?

It is usually configured inside a location block.

Example:

location /api {
    proxy_pass http://backend;
    proxy_read_timeout 120s;
}

It may also be configured at the http or server level when the same timeout should apply to multiple locations.

Check the Current Configuration

Search the configuration files:

grep -R proxy_read_timeout /etc/nginx

Example output:

proxy_read_timeout 60s;

Change proxy_read_timeout

Edit the configuration file.

sudo nano /etc/nginx/conf.d/default.conf

Example:

location / {

    proxy_pass http://127.0.0.1:3000;

    proxy_read_timeout 180s;

}

Save the file.

Test the Configuration

Always verify the configuration before reloading Nginx.

sudo nginx -t

Expected output:

nginx: the configuration file syntax is ok

nginx: configuration file test is successful

Reload Nginx

Apply the changes.

sudo systemctl reload nginx

Verify:

sudo systemctl status nginx

Expected output:

Active: active (running)

Relationship with proxy_connect_timeout

These directives serve different purposes.

| Directive               | Purpose                                                       |
| ----------------------- | ------------------------------------------------------------- |
| `proxy_connect_timeout` | Time allowed to establish a connection to the upstream server |
| `proxy_send_timeout`    | Time allowed to send the request to the upstream server       |
| `proxy_read_timeout`    | Time allowed to wait for the upstream server's response       |

All three work together to control different phases of reverse proxy communication.

Recommended Values

| Application        | Suggested Value |
| ------------------ | --------------- |
| Static API         |             30s |
| REST API           |             60s |
| Web application    |         60–120s |
| Long-running tasks |        180–300s |
| File generation    |    300s or more |

For most production environments:

proxy_read_timeout 60s;

is a sensible default.

Common Issues

504 Gateway Timeout

This is the most common symptom.

Possible causes include:

Slow backend application.

Long-running database queries.

External API requests.

High server load.

Timeout value too low.

Increasing the Timeout Does Not Improve Performance

If the backend consistently requires several minutes to generate responses, increasing the timeout only causes clients to wait longer.

Instead, investigate:

Slow application logic.

Database performance.

Network latency.

External service dependencies.

Optimizing the backend usually provides a better long-term solution.

Confusing proxy_read_timeout with fastcgi_read_timeout

These directives apply to different upstream protocols.

PHP-FPM
    │
    ▼
fastcgi_read_timeout
Node.js / Java / Go / Python
    │
    ▼
proxy_read_timeout

Choosing the correct directive depends on how Nginx communicates with the backend.

Best Practices

Configure timeout values based on your application's expected response times.

Investigate slow backend services before increasing timeout values.

Test configuration changes with nginx -t.

Reload Nginx after modifying the configuration.

Monitor upstream response times and logs to identify bottlenecks.

Related Articles

Nginx fastcgi_read_timeout Explained

Nginx keepalive_timeout Explained

Nginx worker_processes Explained

Nginx worker_connections Explained

PHP max_execution_time Explained

Conclusion

The proxy_read_timeout directive determines how long Nginx waits for a response from an upstream server when acting as a reverse proxy. It is essential for applications built on Node.js, Java, Go, Python, and other backend technologies.

For most production environments, a timeout of 60 to 120 seconds provides a good balance between responsiveness and reliability. If timeout errors occur regularly, focus on optimizing the backend application and infrastructure rather than relying solely on larger timeout values.