Hi Friends! If your site suddenly shows a 504 Gateway Timeout error while Nginx is running, you may need to fix the 504 Gateway Timeout.

This means:

“Nginx was able to reach the backend service, but the backend took too long to respond.”

This usually happens because:

• Your application is responding slowly.
• The server is under a high CPU or memory load.
• A database query is taking too long.
• Timeout settings between Nginx and the backend don’t match.
• A Backend container or pod is restarting or unhealthy.

If you are seeing a 502 Bad Gateway error instead of a 504, the troubleshooting steps are different. You can check our guide on How to Fix 502 Bad Gateway in Nginx.

Quick Fix: 504 Gateway Timeout in Local Nginx Setup

If Nginx is running directly on your server (not inside Docker or Kubernetes), try the steps below.

Step 1: Check Nginx Error Logs

First, check the Nginx error logs. They usually tell you if the request is timing out while waiting for the backend.

# sudo tail -f /var/log/nginx/error.log

A common error you can see in the Nginx Logs:

upstream timed out (110: Unknown error) while connecting to upstream

upstream timed out (110: Connection timed out)

This means Nginx was able to reach the backend service, but the backend did not respond in time.

Step 2: Test the Backend Service

Next, check if the backend application is responding.

# curl http://localhost:3000

If the response is very slow, there may be an issue in the application. If the response does not return, the problem might be in the database or server resources. These issues are likely not related to Nginx.

Step 3: Increase Nginx Timeout Settings

By default, Nginx waits about 60 seconds for a response from the backend server. If the backend takes longer than that, Nginx stops waiting and returns a 504 Gateway Timeout.

In our case, the application takes around 70 seconds to fetch data from the database. Since this is longer than the default Nginx timeout, Nginx returns a 504 error.

To fix this, we can increase the timeout values so Nginx waits longer for the backend response.

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_connect_timeout 100s;
    proxy_send_timeout 100s;
    proxy_read_timeout 100s;
}

Here we increased the timeout to 100 seconds, which gives the backend enough time to complete the request.

After updating the configuration, reload Nginx:

# sudo nginx -t
# sudo systemctl reload nginx

Once the timeout is increased, Nginx will wait longer for the backend response. The 504 Gateway Timeout error should no longer be there.

Note: Increasing the timeout may fix the error temporarily. If the application consistently takes too long to respond, it’s better to investigate backend performance. You should also check database queries. Additionally, consider server resource usage.

Quick Fix: 504 Gateway Timeout in Docker Setup

If Nginx and your application are running inside Docker containers, a 504 Gateway Timeout usually means one of two things.

• The backend container is slow to respond.
• Nginx cannot communicate with it properly.

Follow the steps below to troubleshoot and fix the issue.

Step 1: Check if the Containers Are Running

First, verify that both the Nginx container and the backend container are running.

# docker ps

If the backend container is not listed, it means the application container is not running. In that case, start it:

# docker start <CONTAINER_NAME>

If the container is already running but the application inside it is not responding properly, you can restart it:

# docker restart <CONTAINER_NAME>

Once the backend container is running and healthy, then Nginx will forward requests to the backend application.

Step 2: Check Docker Network Configuration

Another common issue in Docker setups is network configuration. Sometimes Nginx may show an error like this:

host not found in upstream "backend-app"

This happens when the Nginx container cannot resolve the backend container name. When the containers are not connected to the same Docker network.

To fix this issue, we can create a network and keep both containers in the same network.

# docker network create nginx-net

Then deploy both containers into the same network using the option “–network”

Command to run “Backend Container”:

docker run -d \
  --name backend-app \
  --network nginx-net \
  -p 3000:3000 \
  backend-application

Command to run “Nginx Container”:

# docker run -d \
-p 8080:80 \
--network nginx-net \
-v $(pwd)/default.conf:/etc/nginx/conf.d/default.conf \
--name nginx-container \
nginx

Once both containers are on the same network, Nginx can reach the backend using the container name. In our case, the container name for the application is “backend-app”

Example configuration in the Nginx configuration file:

proxy_pass http://backend-app:3000;

After making changes to the Nginx configuration file, reload Nginx so the new settings take effect. And as we are using a Docker setup, we need to restart the container.

# docker restart nginx-container

Step 3: Check Backend Container Logs

If the backend application and nginx are running, but the request is taking more than 60 sec or failing. Then the next step is to check the backend logs.

# docker logs <CONTAINER_NAME>

The logs can help you to identify issues such as application crashes, database connection problems, or long-running requests.

A common error you can see in the Docker container:

upstream timed out (110: Unknown error) while connecting to upstream

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

Step 4: Increase Nginx Timeout (If the Application Is Slow)

If the backend container takes longer to process requests, you need to increase the Nginx timeout values.

location / {
    proxy_pass http://backend-app:3000;
    proxy_connect_timeout 100s;
    proxy_send_timeout 100s;
    proxy_read_timeout 100s;
}

Reload Nginx in the Docker container

# docker exec nginx-container nginx -t
# docker exec nginx-container nginx -s reload

504 vs 502 in Nginx (Important Difference)

When Nginx works as a reverse proxy, it communicates with a backend service like an application server or API. If something goes wrong in this communication, Nginx may return errors like 502 Bad Gateway or 504 Gateway Timeout.

These two errors look similar, but they happen for different reasons. Also, read our guide on How to Fix 502 Bad Gateway in Nginx.

In simple terms:

• 502 means the backend is not reachable or broken.
• 504 means the backend is reachable but too slow to respond.

Understanding this difference helps you quickly to identify whether the issue is related to backend connectivity or backend performance.

Common Causes of 504 Gateway Timeout in Nginx.

A 504 Gateway Timeout usually happens when the backend service takes too long to respond. Below are some common situations where this error can occur.

• Slow application response – If the backend takes too long to respond, Nginx waits only until the configured timeout. After that, it returns a 504 Gateway Timeout error.
• Long-running database queries – Some requests may trigger heavy database queries. If the query takes too long, the response may exceed the Nginx timeout.
• High CPU or memory usage – When the application or backend service is under heavy load, applications may respond slowly. Which can lead to timeout errors.
• Incorrect timeout configuration – Timeout settings like proxy_connect_timeout, proxy_send_timeout, or proxy_read_timeout are set too low. Some requests take longer to finish, and once the configured timeout is reached, Nginx returns a 504 Gateway Timeout error.
• Network delays between services – In setups like Docker or microservices, requests often travel between multiple services. If there are network delays, the response may take longer, and Nginx may return a 504 Gateway Timeout error.

Conclusion

A 504 Gateway Timeout error in Nginx occurs when the backend service takes longer than the configured timeout to respond.

In most cases, reviewing the backend performance and adjusting timeout settings in Nginx can resolve the issue.

Understanding how Nginx communicates with backend services can help you troubleshoot timeout problems more quickly in real-world environments.