NGINX Timeouts: Complete Guide to Configuring and Disabling

Introduction

NGINX is a high-performance web server and reverse proxy that handles thousands of concurrent connections. However, its default timeout settings can cause premature disconnections for long-running requests or slow clients. This guide provides a comprehensive overview of NGINX timeout directives, how to configure them, and when disabling them is appropriate. We’ll cover proxy timeouts, keepalive settings, client body timeouts, and more, with practical examples and best practices.

Understanding NGINX Timeout Directives

NGINX uses several timeout directives to manage connection lifecycles. Each serves a specific purpose and should be tuned based on your application’s requirements. Below are the most common ones:

1. proxy_read_timeout

Defines the timeout for reading a response from the proxied server. If the backend takes too long to send data, NGINX closes the connection. Default is 60 seconds.

proxy_read_timeout 120s;

2. proxy_connect_timeout

Sets the timeout for establishing a connection with the proxied server. Default is 60 seconds.

proxy_connect_timeout 30s;

3. proxy_send_timeout

The timeout for transmitting a request to the proxied server. If the backend is slow to accept data, NGINX times out. Default is 60 seconds.

proxy_send_timeout 60s;

4. keepalive_timeout

Controls how long an idle keepalive connection remains open. Default is 75 seconds. Set to 0 to disable keepalive.

keepalive_timeout 65;

5. client_body_timeout

Defines the timeout for reading the client request body. Default is 60 seconds.

client_body_timeout 60s;

6. client_header_timeout

Timeout for reading the client request header. Default is 60 seconds.

client_header_timeout 60s;

7. send_timeout

Timeout for transmitting a response to the client. Default is 60 seconds.

send_timeout 60s;

How to Disable NGINX Timeouts

Disabling timeouts is generally not recommended because it can lead to resource exhaustion. However, for specific long-running tasks (e.g., file uploads, streaming, WebSocket connections), you may need to increase or disable certain timeouts. To effectively disable a timeout, set its value to 0. For example:

proxy_read_timeout 0;
proxy_send_timeout 0;
keepalive_timeout 0;

Note that setting keepalive_timeout 0 disables keepalive connections entirely, which may increase connection overhead. For WebSocket support, you’ll also need to configure the proxy_http_version and proxy_set_header Upgrade directives.

Best Practices for Configuring Timeouts

Instead of disabling timeouts, consider adjusting them based on your application’s behavior:

• For slow backends: Increase proxy_read_timeout and proxy_connect_timeout.
• For long uploads: Increase client_body_timeout and proxy_send_timeout.
• For high-traffic sites: Use shorter timeouts to free up resources quickly.
• For WebSockets: Set proxy_read_timeout to a high value (e.g., 86400s for 24 hours) and ensure proxy_http_version 1.1 and proxy_set_header Upgrade $http_upgrade are configured.

Example Configuration

Below is a sample NGINX configuration that balances performance and reliability:

http {
    keepalive_timeout 65;
    client_body_timeout 60s;
    client_header_timeout 60s;
    send_timeout 60s;

    server {
        listen 80;
        server_name example.com;

        location /api/ {
            proxy_pass http://backend;
            proxy_connect_timeout 30s;
            proxy_read_timeout 120s;
            proxy_send_timeout 60s;
        }

        location /ws/ {
            proxy_pass http://websocket-backend;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_read_timeout 86400s;
        }
    }
}

Monitoring and Debugging Timeouts

To identify timeout issues, check NGINX error logs (/var/log/nginx/error.log) for messages like “upstream timed out” or “client timed out”. You can also enable debug logging for specific directives:

error_log /var/log/nginx/error.log debug;

Use tools like curl with --max-time to simulate slow connections and test your timeout settings.

Conclusion

NGINX timeouts are essential for maintaining server stability and preventing resource leaks. While disabling them entirely is possible, it’s rarely advisable. Instead, tune each directive to match your application’s needs. Always test changes in a staging environment before deploying to production. For further reading, refer to the official NGINX documentation.