How to Fix 504 Gateway Timeout Errors in NGINX

Is your web application throwing 504 Gateway Timeout errors during traffic spikes? Nothing is more stressful than seeing your error monitoring channel light up with alert notifications while users face blank screens.

When server traffic surges, page requests stall, and customers cannot complete purchases or access their accounts.

The good news is that a 504 status code tells you exactly where the breakdown happened. Unlike a 500 internal crash, a 504 error means your edge reverse proxy failed to receive a timely response from an upstream backend server.

In this step-by-step guide, we will show you how to diagnose the root cause and fix 504 timeouts permanently, from quick NGINX configuration tuning to asynchronous worker queues.

Executive Summary

  • The Meaning of 504: An HTTP 504 error occurs when NGINX or an edge load balancer waits for an upstream application server (Node.js, Python, PHP-FPM) that fails to respond before the timeout window expires.
  • Common Root Causes: Slow database queries, exhausted connection pools, blocking synchronous tasks, and uncalibrated proxy buffer limits.
  • Method 1 (Recommended): Tune NGINX timeout and buffer directives (proxy_read_timeout, proxy_connect_timeout, proxy_buffers) to handle bursty workloads.
  • Method 2 (Developer Architecture): Decouple heavy operations into asynchronous background workers using Redis and message queues like BullMQ or Celery.
  • Database Synergy: Pair proxy optimizations with PgBouncer connection pooling to prevent database lockups during concurrent traffic surges.

Table of Contents

  • [Executive Summary](#executive-summary)
  • [504 Gateway Timeout Causes vs Production Fixes](#504-gateway-timeout-causes-vs-production-fixes)
  • [What Happens Behind the Scenes During a 504 Timeout](#what-happens-behind-the-scenes-during-a-504-timeout)
  • [Method 1: Tuning NGINX Proxy Timeouts and Buffers (Recommended)](#method-1-tuning-nginx-proxy-timeouts-and-buffers-recommended)
  • [Method 2: Offloading Heavy Workloads to Background Queues](#method-2-offloading-heavy-workloads-to-background-queues)
  • [Pro Tips for Eliminating Upstream Database Bottlenecks](#pro-tips-for-eliminating-upstream-database-bottlenecks)
  • [Frequently Asked Questions](#frequently-asked-questions)
  • [Related Guides & Next Steps](#related-guides-and-next-steps)
  • [Primary Sources & References](#primary-sources-and-references)

504 Gateway Timeout Causes vs Production Fixes

Bottleneck LayerWhy 504 Error OccursImmediate Operational FixLong-Term Architectural Defense
NGINX Reverse ProxyDefault 60s timeout expires during slow requestIncrease proxy_read_timeout to 120sAdd upstream keepalive pools and micro-caching.
Node.js / Python APIEvent loop blocked by CPU-heavy processingRestart workers and increase cluster countOffload PDF/image generation to background worker tasks.
Relational DatabaseSlow table scans lock database connectionsTerminate blocking locks and increase pool sizeAdd query indexing and deploy PgBouncer connection pooling.
External WebhookThird-party payment gateway takes too longSet strict HTTP client timeouts (5s max)Wrap third-party API calls in circuit breakers.

What Happens Behind the Scenes During a 504 Timeout

In our comprehensive handbook on scaling high-traffic web applications, we examined modern multi-tier web architectures. In these systems, an edge web server like NGINX acts as a reverse proxy in front of application instances.

When a visitor requests a page, NGINX forwards the HTTP request over an internal network socket to your backend server. NGINX then waits for the backend to generate the HTML or JSON response.

By default, NGINX waits exactly 60 seconds. If your backend application server takes 60.1 seconds to respond, NGINX closes the connection and returns an HTTP 504 Gateway Timeout response to the visitor.

The backend application might still be working on the request, but the user is greeted with a broken error page. Resolving this requires adjusting proxy thresholds and speeding up upstream processing.

If your backend processes valid requests that naturally require more than 60 seconds, such as complex report generation or batch data imports, tuning NGINX timeout directives provides immediate relief.

Step 1: Open Your NGINX Configuration File

First, connect to your web server using SSH. Open your site’s NGINX server block configuration file using your preferred terminal editor:

sudo nano /etc/nginx/sites-available/your-domain.conf

If you manage a global reverse proxy, you can also apply these directives inside the http block of /etc/nginx/nginx.conf.

Step 2: Configure Proxy Timeout Directives

Next, locate the location / block that routes requests to your upstream backend. Add or update these four calibrated directives:

location / {
    proxy_pass http://backend_upstream;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # Timeouts to prevent premature 504 errors
    proxy_connect_timeout 60s;
    proxy_send_timeout    120s;
    proxy_read_timeout    120s;
    send_timeout          120s;

    # Buffer settings for large response headers
    proxy_buffer_size          128k;
    proxy_buffers              4 256k;
    proxy_busy_buffers_size    256k;
}

Setting proxy_read_timeout 120s doubles the amount of time NGINX will wait for upstream application servers before triggering a 504 error.

Step 3: Test and Reload NGINX

Before applying the changes, test your configuration syntax to ensure there are no missing semicolons or typos:

sudo nginx -t

If the test outputs syntax is ok and test is successful, reload NGINX gracefully without dropping active connections:

sudo systemctl reload nginx

Tip: Pro Tip: Always set proxy_http_version 1.1 paired with proxy_set_header Connection "" in your upstream block. This enables HTTP keepalive reuse, eliminating thousands of repetitive TCP three-way handshakes between NGINX and your backend.

Method 2: Offloading Heavy Workloads to Background Queues

Increasing proxy timeouts to two minutes fixes immediate errors, but forcing users to wait minutes for a web page harms user experience. For long-running operations, decoupling work into asynchronous background queues is the best solution.

Step 1: Identify Blocking Operations

Audit your application code for tasks that take longer than 500 milliseconds to complete. Common culprits include:

  • Sending transactional email sequences or push notifications.
  • Generating complex PDF invoices or resizing images.
  • Calling external third-party payment, shipping, or AI APIs.

Step 2: Implement a Redis-Backed Job Queue

Instead of running heavy tasks inside your web request handler, push a lightweight job descriptor into a Redis queue using tools like BullMQ for Node.js or Celery for Python:

import { Queue } from 'bullmq';
import Redis from 'ioredis';

const connection = new Redis(process.env.REDIS_URL);
const reportQueue = new Queue('report-generation', { connection });

// Fast HTTP handler that never times out
export async function handleReportRequest(req, res) {
  const { userId, reportFilters } = req.body;

  // Add task to background queue in milliseconds
  const job = await reportQueue.add('generate-monthly-report', {
    userId,
    reportFilters,
    timestamp: Date.now()
  });

  // Return immediate 202 Accepted response
  return res.status(202).json({
    status: 'queued',
    jobId: job.id,
    message: 'Report is generating in the background.'
  });
}

Step 3: Process Tasks in a Dedicated Worker Thread

In a separate background worker process, consume jobs from the queue and perform the heavy calculations:

import { Worker } from 'bullmq';

const reportWorker = new Worker('report-generation', async (job) => {
  console.log(`Processing report job ${job.id} for user ${job.data.userId}`);
  // Perform complex database queries and write file to S3
  await compileReportData(job.data);
  console.log(`Finished job ${job.id}`);
}, { connection });

Because your web handler responds with HTTP 202 Accepted within 20 milliseconds, NGINX never triggers a 504 Gateway Timeout error.

Pro Tips for Eliminating Upstream Database Bottlenecks

In many production incidents, 504 Gateway Timeout errors are caused by database saturation rather than slow application code.

When hundreds of concurrent visitors hit your platform, each web worker opens a separate database connection. If your PostgreSQL database hits its max_connections ceiling, queries queue up indefinitely until NGINX times out.

To solve this, implement lightweight connection pooling. As detailed in our guide on how to fix PostgreSQL too many connections with PgBouncer, deploying PgBouncer in transaction pooling mode allows thousands of concurrent web requests to share a compact pool of database connections.

Additionally, add covering indexes on slow query columns and use Redis to cache read-heavy database responses at the edge.

Frequently Asked Questions

What is the difference between a 502 Bad Gateway and a 504 Gateway Timeout?

A 502 Bad Gateway error means the upstream backend server crashed or actively rejected the connection. A 504 Gateway Timeout error means the backend accepted the connection, but took longer to respond than the proxy was configured to wait.

Can a client-side network problem cause a 504 error?

No. An HTTP 504 error is strictly a server-side communication failure between the reverse proxy (like NGINX, Cloudflare, or AWS ALB) and the upstream application backend.

What should I do if my cloud load balancer times out before NGINX?

If you run behind AWS Application Load Balancer (ALB) or Cloudflare, ensure your load balancer timeout is slightly longer than your NGINX proxy_read_timeout. If AWS ALB times out at 60 seconds while NGINX is set to 120 seconds, the cloud balancer will return a 504 before NGINX finishes.

How can I verify that my upstream application server is running?

Use curl -I http://127.0.0.1:3000/health directly on your server. If the command returns an immediate HTTP 200 OK, your backend is running and the timeout is caused by a slow specific endpoint.

We hope this tutorial helped you learn how to fix 504 Gateway Timeout errors in NGINX and eliminate backend latency bottlenecks.

Authored by the TeckScaler Editorial Engineering Team, this guide is part of our high-traffic systems engineering series.

You might also want to check out these related guides from our cloud infrastructure cluster:

If your enterprise requires custom web engineering, performance optimization, or cloud migration, explore TeckScaler’s enterprise IT solutions or contact our engineering team.

Primary Sources & References

  1. NGINX Official Documentation: Module ngx_http_proxy_module
  2. IETF RFC 9110: HTTP Semantics – Section 15.6.5: 504 Gateway Timeout
  3. BullMQ Official Documentation: High-Performance Node.js Job Queues
  4. PostgreSQL Documentation: Connection Pooling Architecture

One comment

Leave a Reply

Your email address will not be published. Required fields are marked *