How to Fix 504 Gateway Timeout on Nginx (Real VPS Case)

 

Introduction

A 504 Gateway Timeout error is one of the most common and frustrating problems when running applications behind Nginx, especially on a VPS.
I personally encountered this issue while deploying a production backend behind Nginx as a reverse proxy.

In this article, I’ll explain what causes a 504 Gateway Timeout, how to identify the real problem, and how to fix it properly using real VPS examples — not theory.

What Is a 504 Gateway Timeout?

A 504 Gateway Timeout occurs when:

• Nginx acts as a reverse proxy

• Nginx forwards a request to an upstream server (backend)

• The upstream server does not respond in time

So technically:

Nginx is working, but your backend is slow, unreachable, or misconfigured.

Common Causes of 504 Errors on VPS

From real-world cases, these are the most frequent causes:

1. Backend server is down

• Node.js / Python / Go app not running

• Process crashed

• Wrong port

2. Timeout configuration too low

• Default Nginx timeout is often too short

• Backend needs more processing time

3. Wrong reverse proxy configuration

• Incorrect proxy_pass

• Missing headers

• HTTPS upstream without proper config

4. Network or DNS issue

• Upstream domain not reachable

• SSL handshake delay

Step 1: Check If Your Backend Is Running

Before touching Nginx, always check your backend first.

Example (Node.js backend on port 3000):

curl http://127.0.0.1:3000

If:

• Connection refused → backend not running

• No response → backend frozen

• Response OK → move to Nginx config

Also check running processes:

pm2 status
# or
ps aux | grep node

Step 2: Check Nginx Error Logs
This step tells you the truth.
sudo tail -f /var/log/nginx/error.log

Typical 504 log:
upstream timed out (110: Connection timed out) while reading response header from upstream

This confirms:

Backend is too slow or unreachable

Step 3: Fix Nginx Timeout Configuration

This is the most common fix.

Open your Nginx config:

sudo nano /etc/nginx/sites-available/default

Add or update these values:

location / {
    proxy_pass http://127.0.0.1:3000;

    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
}

Important

• proxy_read_timeout is the most critical

• Increase it if your backend does heavy processing

Step 4: Test and Reload Nginx

Always test before reload:

sudo nginx -t

If OK:

sudo systemctl reload nginx


Step 5: Real VPS Case (What Actually Happened)
In my case:

Backend was hosted on a cloud platform
Nginx proxied requests via HTTPS
Default timeout was too low
Result: 504 on every API call
The fix:
Increased proxy_read_timeout
Added proxy_ssl_server_name on
Set correct Host header
After that:
 API worked normally
 No more random 504 errors

How to Prevent 504 Errors in Production
Use this checklist:
Always monitor backend uptime
Use process managers (PM2, Supervisor)
Set realistic timeout values
Avoid heavy blocking requests
Add health check endpoints

Conclusion
A 504 Gateway Timeout on Nginx is rarely an Nginx problem.

Most of the time, it’s a backend performance or configuration issue.
By:
Checking backend status
Reading Nginx logs
Adjusting timeout values
You can fix 90% of 504 errors in minutes.

Final Tip
If you see a 504 error:
Don’t panic
Check logs first
Fix the real bottleneck