Skip to main content

Fix an Nginx 502 in front of an ASP.NET Core app

· 7 min read
OmmLabs · Sponsored by Omm Rudraksha

An Nginx 502 response tells you that a gateway request failed. It does not identify, by itself, whether the backing ASP.NET Core service stopped, the proxy points at the wrong listener, or another upstream problem occurred.

This guide develops a read-first investigation using a disposable application called demo-web.service. It shows how Server App Manager's separate service, log and website views help you narrow the problem without treating a restart as the first diagnostic step.

Draw the request path you are investigating​

Write the intended route as a short sequence: public URL, Nginx virtual host, configured upstream, application listener and relevant dependencies.

The browser's public HTTPS port is often different from the internal application port. A unit name can differ from both the website name and deployment folder. Keep those identities separate in your notes.

Use the route actually configured on the server. Do not copy another application's port simply because both applications run .NET. On a shared host, an incorrect assumption can direct testing or maintenance at an unrelated service.

Confirm the public observation​

Open Website Health for the affected registered URL. Read the exact response code, error and timestamp. Run a manual check when you need a fresh observation.

A public 502 is different from a DNS failure, TLS error or connection timeout. Preserve that distinction before looking for application logs. If the browser and dashboard differ, compare the requested path and the network from which each request originated.

The dashboard's probes run from your PC. A public endpoint can therefore be reachable from Ubuntu but unavailable from your network, or the reverse. The location of the observation matters when interpreting a result.

Inspect the intended application unit​

Open the registered application's service details. Check its state and main PID before requesting a change.

If the unit is stopped or failed, read its recent journal. Find the first useful startup failure in the relevant attempt. A later retry or shutdown line may describe a consequence rather than the cause.

If the unit is active, continue investigating. An active service is not a promise that it is listening on the port Nginx expects, returning a correct response, or ready to serve a particular application route.

Compare the listener with the upstream​

With the server owner's read-only diagnostic workflow, identify the actual local listener associated with the application. Compare its address and port with the proxy's configured destination.

A unit that listens on one port while the proxy forwards to another gives a specific inconsistency to investigate. Likewise, an IPv4 versus IPv6 binding difference or a socket path can matter in an existing configuration.

The Nginx proxy module documentation describes upstream forwarding. Keep the article's example ports out of production configuration: the intended destination must come from your own reviewed installation.

Read a small Nginx error excerpt​

Ask the authorized operator for the error-log entries corresponding to the failed request time and virtual host. Keep the excerpt bounded and sanitized.

Compare the upstream target and failure description with the listener observation. A connection refusal, upstream closure and timeout can point toward different next checks, even when the browser reports a similar gateway symptom.

The dashboard's application journal view is not a general Nginx error-log editor or unrestricted terminal. Use the operator's established log access for the proxy layer. Do not assume the absence of an application error means the proxy successfully reached that application.

Use a stopped-service example in a lab​

For a controlled exercise, begin with a working disposable site and a known systemd service. Record the public response, the unit state and the local listener.

The lab owner can then stop the sample service as an explicitly approved test. Observe the changed service state and the public result. Record what the actual installation reports rather than expecting every possible setup to produce an identical page or message.

Restore the sample through the authorized maintenance procedure and verify both layers again. This demonstrates a relationship between a missing backing process and a gateway failure without presenting fictional production evidence.

Use a wrong-upstream example separately​

A second disposable exercise can point a lab proxy at an unused local port while leaving the sample application running on its real listener.

The distinguishing evidence should be clear: the service is active, its real local endpoint answers, and the proxy's destination does not match that endpoint. Treat that as a configuration investigation rather than a reason to restart the healthy application repeatedly.

Only the lab owner should edit the configuration for this exercise. Keep a known-good copy and a recovery plan. The dashboard intentionally does not provide an Nginx configuration editor.

Choose the repair from the evidence​

If an application failed to start, address the identified application problem through its owner. If the configured upstream is wrong, review the proxy change through the server's existing configuration process.

A dependency failure can leave a listener present while application requests still fail. In that case, inspect the dependency through the appropriate operator rather than broadening the restart to unrelated services.

Record why the proposed change follows from the observations. This short explanation makes the maintenance review much more useful than a list of commands executed without their intended effect.

Validate before applying a proxy change​

When a proxy configuration change is authorized, validate the installed Nginx configuration using the verified binary and layout. The dashboard's optional Nginx controls perform configuration validation before a reload or restart.

A validation failure is a reason to stop and inspect the error, not a prompt to bypass the test. A successful syntax check also does not prove the intended website-to-upstream mapping is correct.

The Nginx control documentation describes configuration reloading and worker behavior. Check the current installation's supported management path with its owner before choosing between reload and restart.

Retest the same meaningful path​

After the authorized repair, repeat the checks that established the problem. Compare the unit state, actual listener, proxy destination and public URL.

Use the same meaningful application path where possible. A static landing page can answer while a database-backed page still fails. Conversely, an application can intentionally return an authentication response on a protected route.

The result you need is the response expected for that particular route and caller. Keep “HTTP request completed” separate from “the application function recovered” in the incident record.

Handle a timeout without compounding the incident​

If an operation times out, inspect the actual service and pending work before repeating it. A client deadline can expire while a remote systemd job continues.

Recheck timestamps when reading logs. A newly visible entry may describe the original request, a later health probe or a fresh startup attempt. Correlate observations before deciding another component must now be restarted.

Escalate with the smallest useful package of evidence: target unit and environment, public response, sanitized proxy excerpt, observed listener and the exact operation result. Keep credentials and full configuration dumps out of public issues.

Close with a cause and a verified outcome​

A useful incident record explains which part of the path was wrong and what evidence supported the conclusion. It identifies the approved change and the checks that passed afterwards.

For an unresolved case, state the remaining uncertainty just as clearly. “The application listener answers locally, but the proxy's upstream request still times out” gives the next operator a better starting point than “Nginx is broken.”

Continue with the Nginx guide, Website Health guide and service restart walkthrough for the corresponding dashboard workflows.