Bad gateway

The Bad gateway error means that a server acting as a gateway or proxy received an invalid or no response from an upstream server. This is a global ROOT-level error that commonly appears in web servers, APIs, load balancers, and reverse proxy setups. It can occur across Linux and Windows systems, Java and Spring Boot applications, Docker containers, cloud platforms, and microservice architectures when inter-service communication fails.

When does this error occur?

  • A reverse proxy forwards a request to an upstream service that is down
  • An API gateway cannot get a valid response from a backend service
  • Timeouts or connection resets between proxy and upstream server
  • Misconfigured upstream host, port, or protocol
  • Overloaded backend services failing to respond correctly

Root cause of Bad gateway

At the network and application boundary, Bad gateway occurs when an intermediary server successfully receives a client request but fails to obtain a valid response from the next server in the chain. This can be caused by upstream service crashes, incorrect routing, protocol mismatches, connection failures, or invalid responses that the gateway cannot parse or forward.

How to fix the error (step-by-step)

Linux / macOS

Check whether the upstream service is reachable from the gateway. 

curl http://upstream-host:port
ping upstream-host

Verify that the service is listening on the expected port. 

ss -tuln
netstat -tuln

Windows

Test connectivity to the upstream service. 

ping upstream-host
tracert upstream-host

Confirm that the backend service is running and accessible.

Java / Spring Boot

Ensure the backend application is running and responding correctly. 

curl http://localhost:8080/health

Check application logs for crashes, exceptions, or long response times. Verify that proxy timeout values are not lower than backend processing time.

Docker / containers

Confirm container networking and service discovery. 

docker ps
docker network inspect bridge

Test connectivity from the proxy container to the backend container. 

docker exec -it <proxy_container> curl http://backend:port

Database / network services

If the upstream depends on a database or external service, ensure those dependencies are reachable and responsive.

Verify the fix

Repeat the original request through the gateway or proxy. The issue is resolved when the gateway consistently receives valid responses from the upstream service and forwards them successfully to clients.

Common mistakes to avoid

  • Restarting the gateway without checking upstream service health
  • Assuming the error is caused by client requests
  • Setting proxy timeouts lower than backend response times
  • Misconfiguring upstream hostnames or ports
  • Ignoring backend application logs

Quick tip

Always monitor upstream service health and response times to prevent Bad gateway errors in proxy-based architectures.

FAQ

Q: Is Bad gateway the same as Service unavailable?

A: No. Bad gateway indicates an invalid response from an upstream server, while Service unavailable means the service is temporarily unable to handle requests.

Q: Can Bad gateway occur even if the backend is running?

A: Yes. It can happen if the backend responds too slowly, crashes mid-request, or returns malformed responses.

Conclusion

The Bad gateway error signals a failure between a gateway and its upstream service. Verifying connectivity, configuration, and backend health resolves the issue. Explore related ROOT gateway and network errors on ErrorFixHub for deeper troubleshooting.

Comments

Post a Comment

Popular posts from this blog

Connection aborted

The Connection aborted error indicates that an established network connection was unexpectedly terminated before the operation could complete. This is a global ROOT error that appears across Linux, Windows, Java, Spring Boot, Dockerized applications, databases, and client-server systems. It means the connection was forcefully closed by the local system, remote peer, or an intermediate network layer. When does this error occur? A client application sends or receives data after the socket has been closed A server process crashes or restarts while handling an active connection Firewall or security software forcibly terminates a connection Network interruptions during long-running requests or uploads Timeout or protocol mismatch causes the OS to abort the connection Root cause of Connection aborted The Connection aborted error occurs when the operating system forcibly closes a TCP connection that is still in use. This can happen due to application-level crashes, i...
Read more

Permission denied

The error Permission denied occurs when an application or user tries to access a file, directory, port, or system resource without sufficient privileges. This error is commonly seen in Linux and Unix-based systems, Git operations, Java applications, Docker containers, and server environments. When Does This Error Occur? When reading or writing a file without the required permissions When executing a script that is not marked as executable When accessing a protected directory or system path When binding to restricted ports or system resources When running commands as a non-privileged user Common examples rm: Permission denied cp: Permission denied chmod: Permission denied docker: Permission denied git: Permission denied Root Cause of Permission denied The operating system enforces access control using ownership and permission rules. Every file and directory has an owner, a group, and a set of permission flags. The Permission denied error occurs when the cur...
Read more

Port already in use

The root error Port already in use occurs when an application attempts to start a network service on a port that is already occupied by another running process. Because operating systems allow only one process to listen on a specific port and protocol combination at a time, this error is common in Linux servers, Windows systems, Java and Spring Boot applications, Docker containers, and database or web server environments. When does this error occur? When starting a server application while another process is already listening on the same port When a previously running service did not shut down cleanly and kept the port open When multiple applications are configured to use the same default port When a Docker container is still bound to a host port When system services occupy common ports such as 8080, 3306, or 5432 Root cause of Port already in use The Port already in use error is raised by the operating system’s networking stack. When a process binds to a TCP ...
Read more