How to Fix 502 Bad Gateway Error in NGINX for .NET Applications (Step-by-Step Guide)

There’s a moment every backend developer eventually faces — everything works perfectly in local, deployment goes smooth, and then production hits you with something completely silent but painful.

For me, it was a simple .NET deployment behind NGINX. Nothing complicated. Just an API update.

And then… boom.

502 Bad Gateway.

No crash logs screaming. No obvious failure in the application. Just a blank failure from NGINX like it refused to talk to my backend at all.

What actually happened in production (ASP.NET Core + NGINX Linux deployment issue)

The setup was pretty standard:

• NGINX acting as reverse proxy
• ASP.NET Core running on Kestrel
• Ubuntu Linux server hosting everything

Flow should’ve been simple:

Client → NGINX → Kestrel (.NET API)

But something broke in between.

The weird part? The .NET service was running fine. No errors. No restarts. Everything looked healthy.

But the browser kept showing 502.

That’s when I realized — this wasn’t a code issue. It was a connectivity issue between layers.

What 502 Bad Gateway means in NGINX for ASP.NET Core applications

Forget textbook definitions. In production, it usually means this:

NGINX tried to reach your backend, but didn’t get a valid response.

This is one of the most common issues in Linux NGINX ASP.NET Core reverse proxy deployments.

• Backend is not reachable
• Wrong Kestrel port configuration
• NGINX proxy_pass mismatch
• Firewall blocking internal traffic
• Wrong environment configuration in systemd

How I Actually Fixed It (Step-by-Step Debugging)

Step 1: Check ASP.NET Core service status in Linux server

systemctl status my-dotnet-api.service

journalctl -u my-dotnet-api.service -f

Systemd service configuration for ASP.NET Core behind NGINX

[Unit]
Description=Running ASP.NET Core on Ubuntu 24.04 Webserver NGINX

[Service]
WorkingDirectory=/home/ubuntu/webapps/project.com # your username
ExecStart=/usr/bin/dotnet /home/ubuntu/webapps/project.com/project.API.dll # your username
Restart=always

RestartSec=10
KillSignal=SIGINT
User=ubuntu # your username

Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=ASPNETCORE_URLS=http://127.0.0.1:5004

[Install]
WantedBy=multi-user.target

Important: Kestrel was running on port 5004, not 5000.

Step 2: Verify Kestrel port in ASP.NET Core Linux environment

ss -tulnp | grep dotnet

curl http://localhost:5004

Backend was working correctly on port 5004.

Step 3: Check NGINX reverse proxy configuration (proxy_pass issue)

location / {
    proxy_pass http://localhost:5000;
}

This is the most common mistake in ASP.NET Core NGINX deployment.

Step 4: Fix proxy_pass for ASP.NET Core backend

proxy_pass http://localhost:5004;

nginx -t
systemctl reload nginx

Step 5: Check firewall for Linux server deployment

ufw status
sudo ufw allow 5004

Step 6: Check NGINX logs for 502 error debugging

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

Before fix:

connect() failed (111: Connection refused) while connecting to upstream

Root cause of 502 Bad Gateway in ASP.NET Core NGINX setup

• ASP.NET Core backend running → OK
• Kestrel port mismatch → ISSUE
• NGINX proxy_pass wrong → ISSUE

Common mistakes in production deployment

• Wrong proxy_pass port
• Not updating ASPNETCORE_URLS
• Not restarting systemd service

Best practices for preventing 502 Bad Gateway errors

• Always verify backend port after deployment
• Use /health endpoint in ASP.NET Core API
• Automate curl-based health checks

Final result after fixing NGINX 502 Bad Gateway issue

Important note: The backend is fully working and NGINX is successfully forwarding requests after the fix.

If you are deploying ASP.NET Core behind NGINX on Linux and facing 502 error, this issue is almost always caused by proxy_pass or backend port mismatch — not application code.

Simple issue. Big impact in production.