Common Nginx Error Log Pattern (.NET / ASP.NET Core)
When upstream sockets, timeouts, body limits, or Docker DNS rules are misconfigured for .NET / ASP.NET Core, Nginx typically records an entry matching the log line below inside /var/log/nginx/error.log:
2026/11/22 20:01:29 [error] 7402#7402: *891 upstream sent too big header while reading response header from upstream, client: 198.51.100.31, server: api.dotnetapp.com, request: "GET /signin-oidc?code=... HTTP/2.0", upstream: "http://127.0.0.1:5000/signin-oidc", host: "api.dotnetapp.com"
Reverse Proxy Architecture & Header Forwarding for .NET / ASP.NET Core
Deploying ASP.NET Core 8 or 9 on Linux with Kestrel behind Nginx is the official Microsoft-recommended architecture for high-performance .NET web APIs, Blazor Server apps, and SignalR hubs. Kestrel listens on http://127.0.0.1:5000 while Nginx terminates TLS, protects against malformed HTTP traffic, enforces upload size limits, and proxies HTTP/1.1 WebSocket upgrades cleanly.
Two .NET-specific issues regularly surface right after putting Nginx in front of Kestrel. First, ASP.NET Core ignores X-Forwarded-For and X-Forwarded-Proto unless app.UseForwardedHeaders() is registered at the very top of Program.cs; causing OpenID Connect / OAuth callbacks (like Azure AD or Auth0) to generate http:// redirect_uri mismatches and breaking HSTS or HTTPS redirection.
Second, ASP.NET Core Identity, Entra ID, and OpenID Connect routinely emit large chunked authentication cookies (Set-Cookie headers exceeding 4 KB–8 KB). Nginx's default proxy_buffer_size is only 4 KB on x86_64 Linux, causing Nginx to crash OAuth sign-in callbacks with HTTP 502 Bad Gateway and log "upstream sent too big header while reading response header from upstream." Raising proxy_buffers and proxy_buffer_size in Nginx resolves this immediately.
If your .NET backend also hosts SignalR hubs or Blazor Server circuits, keeping proxy_http_version 1.1, Upgrade/Connection headers, proxy_cache_bypass $http_upgrade, and an extended proxy_read_timeout ensures long-lived WebSocket circuits remain connected without unexpected Blazor reconnection modals.
For enterprise ASP.NET Core 8 and 9 services hosted on Ubuntu, Debian, or Alpine Linux containers behind Nginx, testing authentication flows (OpenID Connect, JWT Bearer, and cookie sessions) through the live HTTPS proxy before launch prevents the classic 502 header-buffer crash and HTTPS redirect loop. Configure Kestrel limits cleanly in appsettings.Production.json, keep Nginx proxy_buffer_size at 128k or higher for large claims payloads, verify ForwardedHeaders middleware executes first in Program.cs, and audit systemd journalctl logs alongside /var/log/nginx/error.log to verify clean startup and zero dropped SignalR connections.
Step-by-Step Nginx & .NET / ASP.NET Core Deployment Guide
Apply the Nginx server block above alongside these upstream framework trust-proxy settings so HTTPS detection, real client IPs, and reload safety work reliably in production.
1Register UseForwardedHeaders() First in ASP.NET Core Program.cs
Program.csCall app.UseForwardedHeaders() BEFORE UseAuthentication(), UseHttpsRedirection(), and UseCors() so Kestrel sees the true HTTPS scheme and client IP forwarded by Nginx.
Program.cscsharpusing Microsoft.AspNetCore.HttpOverrides; var builder = WebApplication.CreateBuilder(args); builder.Services.Configure<ForwardedHeadersOptions>(options => { options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto; // Loopback (127.0.0.1) is trusted by default; clear KnownNetworks/Proxies only in isolated Docker networks }); var app = builder.Build(); app.UseForwardedHeaders(); app.UseRouting(); app.UseAuthentication(); app.UseAuthorization(); app.MapControllers(); app.Run("http://127.0.0.1:5000");2Increase Nginx Proxy Header Buffers for ASP.NET Core Identity / OIDC Cookies
/etc/nginx/sites-available/api.dotnetapp.com.confAdd proxy_buffer_size and proxy_buffers inside your Nginx location block so large JWT claims and OIDC Set-Cookie headers never trigger 502 "upstream sent too big header" errors.
/etc/nginx/sites-available/api.dotnetapp.com.confnginxproxy_buffer_size 128k; proxy_buffers 4 256k; proxy_busy_buffers_size 256k;3Run Kestrel as a Managed systemd Service on Linux
/etc/systemd/system/kestrel-api.serviceConfigure ASPNETCORE_URLS to bind exclusively to loopback 127.0.0.1:5000 and let systemd restart the process automatically on failures.
/etc/systemd/system/kestrel-api.serviceini[Unit] Description=ASP.NET Core Kestrel API [Service] WorkingDirectory=/var/www/dotnet-api ExecStart=/usr/bin/dotnet /var/www/dotnet-api/Api.dll Restart=always RestartSec=5 User=www-data Environment=ASPNETCORE_ENVIRONMENT=Production Environment=ASPNETCORE_URLS=http://127.0.0.1:5000 [Install] WantedBy=multi-user.target4Validate Nginx Config and Verify SignalR / HTTPS Forwarded Scheme
terminalReload Nginx safely and confirm Kestrel receives HTTPS scheme headers without redirect loops.
terminalbashsudo nginx -t && sudo systemctl reload nginx curl -I https://api.dotnetapp.com/health
Common .NET / ASP.NET Core Nginx Reverse Proxy Pitfalls
Review these three production failure modes before reloading Nginx on staging or live servers.
502 "upstream sent too big header" During OAuth / Entra ID Logins
ASP.NET Core splits large authentication tickets across multiple Set-Cookie headers. Nginx's default 4 KB proxy_buffer_size overflows and returns 502 Bad Gateway right on /signin-oidc unless you configure proxy_buffer_size 128k; and proxy_buffers 4 256k;.
Infinite Redirect Loop From app.UseHttpsRedirection() Without UseForwardedHeaders()
When Nginx terminates HTTPS and forwards HTTP to Kestrel port 5000, Kestrel's UseHttpsRedirection() sees an HTTP request and responds with 307 to https://, looping forever unless UseForwardedHeaders() runs first.
Docker Bridge Proxies Rejected by Default KnownProxies
ASP.NET Core only trusts X-Forwarded-* headers from 127.0.0.1 by default. If Nginx runs in a separate Docker container (e.g., 172.18.0.2), you must add the Docker bridge subnet to KnownNetworks (or clear KnownProxies inside an isolated private network).
Complete Your Deployment With Matching Docker Compose & CORS Tools
Pair this Nginx reverse proxy block with healthcheck-gated Docker Compose orchestration and verified browser CORS headers:
Generate a Docker Compose config for ASP.NET Core 8/9 Web API, PostgreSQL 16 (Npgsql), and Redis distributed cache with pg_isready and redis-cli healthchecks.
Fix CORS errors between ASP.NET Core 8/9 Web API and Angular CLI on port 4200. Verify UseCors middleware ordering, AllowCredentials, and HTTPS redirects.
Frequently Asked Questions
- Does ASP.NET Core SignalR require special Nginx headers?
- Yes. SignalR uses WebSockets (and Server-Sent Events fallback). You need proxy_http_version 1.1, Upgrade $http_upgrade, Connection $connection_upgrade, proxy_cache_bypass $http_upgrade, and a high proxy_read_timeout (such as 3600s) so hubs stay connected.
- Why does Nginx return 413 Request Entity Too Large even after setting [RequestSizeLimit] in .NET?
- Nginx inspects Content-Length before forwarding the body to Kestrel. Raise client_max_body_size in Nginx to match or slightly exceed Kestrel's MaxRequestBodySize.
- Should I keep Kestrel listening on HTTPS behind Nginx?
- On the same host (127.0.0.1:5000), terminating TLS at Nginx and proxying plain HTTP over loopback is standard, faster, and avoids managing duplicate internal certificates.
- How do I prevent Nginx from stripping Blazor Server streaming updates?
- Blazor Server relies on a persistent SignalR WebSocket circuit at /_blazor. With HTTP/1.1 Upgrade headers and proxy_buffering off on the SignalR endpoint, DOM diffs stream instantaneously.
Related Nginx Reverse Proxy Guides
Browse all 10 Nginx guides →Nginx Reverse Proxy Config for Socket.IO & WebSockets (Upgrade & 3600s)
Fix WebSocket 400 errors and 60-second disconnects in Nginx for Socket.IO and ws servers. Generate Upgrade, Connection map, and 3600s proxy_read_timeout blocks.
Nginx Reverse Proxy for Docker Compose Services (127.0.0.11 DNS Resolver)
Prevent 502 Bad Gateway and Nginx startup crashes in Docker Compose using resolver 127.0.0.11 and variable proxy_pass for dynamic container restarts.
Nginx Reverse Proxy Config for Django + Gunicorn (SSL, Static & CSRF)
Generate a production Nginx reverse proxy for Django and Gunicorn on port 8000 with SECURE_PROXY_SSL_HEADER, CSRF_TRUSTED_ORIGINS, /static/, and /media/.
Nginx Multi-Service Subpath Routing Config (/api/, /auth/ & /ws/)
Route /api/, /auth/, and /ws/ microservices to separate backend ports under one Nginx HTTPS domain. Master trailing-slash prefix stripping and prevent 404s.