502 Bad Gateway: What It Means and How to Fix It

A 502 Bad Gateway error means one server, acting as a gateway or proxy, asked another server behind it for the page and got an invalid answer back. Your browser reached the site fine; the break is between the site's own servers. Visitors can usually only wait and retry. Site owners fix it by finding which server behind the proxy failed.

By Gary, Greenlight My App. Checked Nov 2, 2026. How we checked this: we read MDN's status code pages, Cloudflare's 502/504 guide, the nginx proxy module docs, Google's crawler docs and Vercel's error docs on Nov 2, 2026, and quote them below. Our team also broke and fixed a throwaway Nginx 1.26.3 proxy on our own machine (everything on 127.0.0.1) on Nov 2, 2026; the screenshots below are from that run. Drafted with AI tools and reviewed by a person before publishing.

What does 502 Bad Gateway mean?

502 Bad Gateway is an HTTP status code. It means a server in the middle (a reverse proxy, load balancer, CDN or app host) forwarded your request to the server behind it and got back something it couldn't use: a refused connection, a crash mid-response or a malformed reply. The middle server then tells your browser "502" instead.

MDN's definition (external): "The HTTP 502 Bad Gateway server error response status code indicates that a server was acting as a gateway or proxy and that it received an invalid response from the upstream server."

"Upstream" just means the server behind the proxy, usually the one running the actual app. Most modern sites have at least one layer in front of the app, so there's almost always somewhere for a 502 to come from.

A 502 can show up as plain text, a branded page from a host or CDN, or variations like "HTTP 502", "502 Proxy Error" and "Bad Gateway: the proxy server received an invalid response". They all mean the same thing.

What causes a 502 error?

A 502 happens when the proxy can't get a valid response from the app behind it. The most common causes are an app that has stopped or crashed, a proxy pointed at the wrong address or port, an app too overloaded to answer, a firewall blocking the proxy, or a response the proxy considers invalid, like oversized headers or broken compression.

Cloudflare's guide lists similar origin-side causes, telling site owners to "Investigate excessive server loads, crashes, or network failures" and to "Identify applications or services that timed out or were blocked."

How to fix a 502 as a visitor

As a visitor, a 502 is almost never caused by your device, so there's little to fix on your side. Wait a minute and reload, try another browser or a private window, switch from Wi-Fi to mobile data, and check the site's status page or social accounts. If it persists for hours, the site owner has to fix it.

Here's who can fix what:

MDN notes the one real exception: "There are many causes of 502 errors, and fixing such problems probably requires investigation by server owners or administrators. Exceptions are client networking errors," for example, a corporate proxy or VPN between you and the site. If a site works on your phone's mobile data but not on your work network, that's the sign.

Does a 502 mean I'm blocked? Not usually. A block typically shows a 403 Forbidden or a branded "access denied" page. A 502 is about the servers failing to talk to each other.

How to fix a 502 on your own site (step by step)

To fix a 502 on your own site, work from the app outward. First confirm the app process is running and answering locally. Then check that the proxy points at the right host and port. Then read the proxy's error log for the exact failure. Finally, look at what changed: a deploy, a config edit or a traffic spike.

Step 1: Is the app running? On a Linux server with systemd, check the app's service (replace myapp with your own unit name):

systemctl status myapp

Step 2: Does the app answer locally? Ask it directly, skipping the proxy. If this fails, the problem is the app, not the proxy:

curl -I http://127.0.0.1:8000/

Step 3: Is it listening on the port the proxy expects? List listening sockets and look for your app's port:

sudo ss -ltnp

Step 4: Read the proxy's error log. On many Linux installs, Nginx writes to /var/log/nginx/error.log; your path may differ:

sudo tail -n 50 /var/log/nginx/error.log

Step 5: Check what changed. If the 502 started right after a deploy, roll back first and debug second. If it started with a traffic spike, check CPU and memory, and whether the app is restarting in a loop.

Step 6: Compare through the proxy and around it. Run curl -I against your public URL too. If the app answers on 127.0.0.1 but the public URL gives 502, the proxy's config or network path is the problem.

502 Bad Gateway on Nginx: common causes and fixes

Nginx returns a 502 when it can't get a valid response from the address in proxy_pass. In practice that's three cases: the app isn't running, proxy_pass points at the wrong port, or the app sends a response Nginx considers invalid, such as headers larger than its buffer. A slow app usually gives a 504 instead.

A minimal reverse proxy, following the nginx docs' own example, sends every request to an app on port 8000:

location / {
    proxy_pass http://localhost:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Case 1: the app is stopped. Nginx tries to connect, nothing is listening, and the error log records a failed connect() "while connecting to upstream". Start the app and the 502 goes away.

Case 2: the wrong port. Same symptom as a stopped app, because from Nginx's view nothing is listening at that address. Compare the port in proxy_pass with the one from ss -ltnp. After editing the config, test and reload:

sudo nginx -t && sudo systemctl reload nginx

Case 3: headers too big. The nginx proxy module docs (external) say proxy_buffer_size covers "the first part of the response received from the proxied server. This part usually contains a small response header; if it exceeds the buffer size, the response is considered invalid." Apps that set many or large cookies can hit this. The fix is raising the buffer for that location, or sending less in headers.

Timeouts are usually 504, not 502. The docs describe proxy_read_timeout (default 60s) as one that "Defines a timeout for reading a response from the proxied server," and proxy_connect_timeout (also 60s by default) notes it "cannot usually exceed 75 seconds." If an app needs longer for one heavy route, raise the timeout for that route only:

location /api/reports {
    proxy_pass http://localhost:8000;
    proxy_read_timeout 120s;
}

What happened when we broke our own test proxy?

We set up Nginx 1.26.3 in a throwaway folder, listening on 127.0.0.1:8088 and forwarding to a tiny Node app on 127.0.0.1:3001, with proxy_read_timeout 5s. Then we broke it on purpose, one way at a time. Nothing left our machine.

The working baseline: curl -I through the proxy returns 200 OK, and the app answers with its hello line.

Then we stopped the app. The proxy kept running and answered 502 Bad Gateway, and the error log named the exact failure:

This is the page a visitor sees from a default Nginx when that happens:

With the app running again but proxy_pass pointed at the wrong port, the result was identical. That's why the log's upstream: address is the fastest clue: it shows where Nginx actually tried to connect.

Putting the port back and reloading fixed it immediately:

A slow route did not give a 502. With a 15-second route behind a 5-second proxy_read_timeout, Nginx gave up at about 5 seconds and returned 504 Gateway Time-out:

All three states side by side, plus ss -ltnp showing both the proxy and the app bound to 127.0.0.1 only:

Worked example. Say your app moved from port 3000 to 8000 in a refactor, but proxy_pass still says http://localhost:3000. curl -I http://127.0.0.1:8000/ returns 200, ss -ltnp shows nothing on 3000, and the public URL gives 502. Change proxy_pass to port 8000, run nginx -t, reload, and the site is back.

502 behind Cloudflare or another CDN

Behind Cloudflare, first check whether the 502 page is branded. Cloudflare's docs say a Cloudflare-branded 502 or 504 means your origin server returned the error, so the fix is on your server or host. A blank, unbranded 502 came from Cloudflare itself, sometimes from a compression problem at the origin.

Cloudflare's 502/504 guide (external), checked Nov 2, 2026: "An HTTP 502 or 504 error indicates that Cloudflare is unable to establish contact with your origin web server." It lists two sources: "502/504 errors from your origin web server (most common)" and "502/504 errors from Cloudflare."

The branding is the tell:

• Branded error page: "Cloudflare returns a Cloudflare-branded HTTP 502 or 504 error when your origin web server responds with a standard HTTP 502 bad gateway or 504 gateway timeout error." Work through the owner steps above on your origin, or contact your host.
• Blank page, no branding: came from Cloudflare. The docs say this "can occur due to a compression issue at the origin, such as when the origin server serves gzip-encoded compressed content but fails to update the content-length header." Try disabling compression at the origin to confirm.
• Cloudflare Tunnel: a 502 with "Unable to reach the origin service" means the tunnel is connected but cloudflared can't reach the service in your ingress rule.

If you need Cloudflare support, their docs ask for the timestamp with time zone, the exact URL that returned the error, and the output of <YOUR_DOMAIN>/cdn-cgi/trace. Other CDNs work the same way: find out whether the CDN or your origin produced the error before changing anything.

502 on app hosts and serverless functions

On app hosts and serverless platforms, a 502 usually means your function or app crashed or exited without sending a response. The platform's edge is the gateway, and your code is the upstream. Check the function logs for the failing route, look for an uncaught error, and roll back if the 502 started with a deploy.

Vercel documents this case by name (external). Its NO_RESPONSE_FROM_FUNCTION error, listed as "502 NO_RESPONSE_FROM_FUNCTION: Bad Gateway," "occurs when a function invocation completes without returning a response." The causes it lists: "A global uncaught exception," "A global unhandled rejection" and "A deployment that introduced incorrect syntax."

In a Next.js API route, the classic version is an async call that throws with nothing catching it. Wrapping the work so every path returns a response turns a confusing 502 into a clear error you control:

export async function GET() {
  try {
    const data = await loadReport();
    return Response.json(data);
  } catch (err) {
    console.error("report failed", err);
    return Response.json({ error: "Report unavailable" }, { status: 500 });
  }
}

Don't return the raw error message or stack trace to the browser. It can leak internal details. Log it server-side and send a short message.

If an AI tool built your backend, it's worth checking that the keys those functions use stay server-side; see CORS policy errors for the related "it works locally but not in production" problem. When the failure is a third-party service your app depends on, check its status first: our guides on whether Supabase is down and whether ChatGPT is down show where to look.

502 vs 503 vs 504: what's the difference?

All three are server-side errors from the server in the middle, but they mean different things. A 502 means the upstream sent a bad answer or the connection failed. A 503 means the server isn't ready to handle the request, often during maintenance or overload. A 504 means the upstream didn't answer in time.

MDN's 504 page (external) draws the 502/504 line clearly: a 504 "is similar to a 502 Bad Gateway, except that in a 504 status, the proxy or gateway did not receive any HTTP response from the origin within a certain time." And if the origin sends a proper error, MDN says it "should be passed on to the client instead of a 502."

How to stop 502s at launch

Most launch-day 502s come from deploys and from apps that crash under first real traffic. Add a health check route, let deploys start the new version before stopping the old one, set timeouts on purpose instead of leaving defaults, catch errors in every API route, and set up an uptime monitor that alerts you before users do.

A launch checklist you can copy:

• A /api/health route that returns 200 only when the app can serve requests
• Deploys that start the new version before the old one stops (most app hosts do this; check yours)
• Every API route returns a response on every path, including errors
• Proxy timeouts set on purpose for slow routes, not raised globally
• An uptime monitor on your homepage and one key API route, with alerts to your phone
• A rollback you've practiced once before launch day

A 502 check isn't a security check, and the other way round. Before launch, our team also ran Greenlight My App's free scan on our own demo Next.js deploy on Nov 2, 2026. It reported 73/100 and flagged missing headers (Content-Security-Policy, X-Content-Type-Options, clickjacking protection) and an HTTP-to-HTTPS redirect. It doesn't test uptime or 502s; pair it with an uptime monitor.

Can a 502 hurt your Google rankings?

A short 502 rarely matters for search. A long one can. Google's crawler docs (external), checked Nov 2, 2026, say: "5xx and 429 server errors prompt Google's crawlers to temporarily slow down with crawling. For Google Search, already indexed URLs are preserved in the index, but eventually dropped." They add that "Any content Google receives from URLs that return a 5xx status code is ignored," and that once the server returns 2xx again, "Google gradually increases the crawl rate for the site."

So the practical rule is speed: fix the 502, confirm the page returns 200 with curl -I, and Google picks the crawl rate back up on its own. Don't serve a 200 page that just says "error"; Google's same page warns that an error message on a 2xx page can show up as a soft 404 in Search Console.

A health route can be this small:

export async function GET() {
  return Response.json({ ok: true });
}

While you're preparing the launch, run the same check on your security headers with the security headers checker. A site that's up but missing basic headers is a different kind of launch problem.

FAQ

What is a 502 gateway error? An HTTP status code meaning a proxy or gateway got an invalid response from the server behind it. The break is between the site's servers, not your device.

Will error 502 fix itself? Often, if it's a brief deploy or traffic spike. If it lasts more than a few minutes, the site owner usually has to restart or fix something.

Does 502 Bad Gateway mean I'm blocked? Usually not. Blocks normally show a 403 or an "access denied" page. A 502 means the site's own servers aren't talking properly.

How to avoid 502 Bad Gateway? Add health checks, deploy without downtime, catch errors in every API route, set timeouts on purpose and monitor uptime with alerts.

Is a 502 my fault or the website's? Almost always the website's. The exception is a network problem on your side, like a VPN or company proxy. Try mobile data to check.

Can a 502 hurt SEO? Brief ones rarely matter. Google says 5xx errors slow its crawling, and indexed URLs that keep returning errors are eventually dropped.

What is the difference between 502 and 504? A 502 is an invalid response or failed connection to the upstream. A 504 means no response arrived in time.

Why do I get a 502 on Cloudflare? A branded Cloudflare 502 means your origin server returned it. A blank, unbranded one came from Cloudflare, sometimes due to origin compression.

Launching soon? Run a free scan with Greenlight My App to check your live site's public code for exposed API keys and missing security headers.