Skip to content

feat(agent): friendly 504 page for paused/timing-out upstreams #438

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
runleveldev wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(agent): friendly 504 page for paused/timing-out upstreams #438

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
33e1758
feat(agent): serve a friendly 504 page for paused or timing-out upstr…
runleveldev Jul 31, 2026
be3ef3c
Potential fix for pull request finding
runleveldev Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions agent/templates/nginx.conf.ejs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,7 @@ http {
location /403.html { }
location /404.html { }
location /502.html { }
location /504.html { }
location /auth-unavailable.html { }
}

Expand Down Expand Up @@ -141,6 +142,17 @@ http {
proxy_pass http://error_pages;
}

<%_ /* A frozen/paused or OOMing-but-alive upstream keeps the socket open
but never replies, so NGINX hits proxy_read_timeout and returns 504. */ -%>
error_page 504 @504;
location @504 {
rewrite ^ /504.html break;
proxy_method GET;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_pass http://error_pages;
}

<%_ if (httpServices.length === 0) { _%>
location / {
proxy_pass http://localhost:3000;
Expand Down Expand Up @@ -210,6 +222,17 @@ http {
proxy_pass http://error_pages;
}

<%_ /* A frozen/paused or OOMing-but-alive upstream keeps the socket open
but never replies, so NGINX hits proxy_read_timeout and returns 504. */ -%>
error_page 504 @504;
location @504 {
rewrite ^ /504.html break;
proxy_method GET;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_pass http://error_pages;
}

<%_ if (authRequired && authServer) { _%>
<%_ /*
oauth2-proxy runs on its own address (this domain's "oauth2-proxy URL").
Expand Down Expand Up @@ -394,6 +417,17 @@ http {
proxy_pass http://error_pages;
}

<%_ /* A frozen/paused or OOMing-but-alive upstream keeps the socket open
but never replies, so NGINX hits proxy_read_timeout and returns 504. */ -%>
error_page 504 @504;
location @504 {
rewrite ^ /504.html break;
proxy_method GET;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_pass http://error_pages;
}

<%_ /* Serve documentation site statically */ -%>
location / {
root /opt/opensource-server/mie-opensource-landing/site;
Expand Down
3 changes: 2 additions & 1 deletion error-pages/502.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,8 @@
<div class="status-code">502</div>
<h1>Service Unavailable</h1>
<p>
A service is configured for this hostname, but the upstream is not responding.
A service is configured for this hostname, but the upstream refused the
connection. The service is likely stopped or has crashed.
</p>
<div class="hostname" id="hostname"></div>
<div class="troubleshooting">
Expand Down
151 changes: 151 additions & 0 deletions error-pages/504.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>504 — Service Paused</title>
<style>
*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }

body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
background: linear-gradient(135deg, #0f0f23 0%, #1a1a2e 50%, #16213e 100%);
color: #e0e0e0;
min-height: 100vh;
display: flex;
align-items: center;
justify-content: center;
position: relative;
overflow: hidden;
}

body::before {
content: '';
position: absolute;
inset: 0;
background-image:
linear-gradient(rgba(255,255,255,0.05) 1px, transparent 1px),
linear-gradient(90deg, rgba(255,255,255,0.05) 1px, transparent 1px);
background-size: 30px 30px;
pointer-events: none;
}

.container {
position: relative;
max-width: 620px;
width: 90%;
padding: 3rem 2.5rem;
background: rgba(0, 0, 0, 0.5);
border: 1px solid rgba(255, 255, 255, 0.1);
border-radius: 20px;
text-align: center;
}

.status-code {
font-size: 5rem;
font-weight: 700;
background: linear-gradient(135deg, #ffb347, #f9a825);
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
background-clip: text;
line-height: 1.1;
}

h1 {
font-size: 1.5rem;
font-weight: 600;
color: #fff;
margin: 0.5rem 0 1.5rem;
}

p {
font-size: 1rem;
line-height: 1.6;
color: #b0b0b0;
margin-bottom: 1rem;
}

.troubleshooting {
margin-top: 1.5rem;
padding: 1.25rem;
background: rgba(255, 255, 255, 0.04);
border: 1px solid rgba(255, 255, 255, 0.1);
border-radius: 10px;
text-align: left;
}

.troubleshooting h2 {
font-size: 0.95rem;
font-weight: 600;
color: #fff;
margin-bottom: 0.75rem;
}

.troubleshooting ul {
list-style: none;
padding: 0;
}

.troubleshooting li {
position: relative;
padding: 0.4rem 0 0.4rem 1.5rem;
font-size: 0.9rem;
line-height: 1.5;
color: #b0b0b0;
}

.troubleshooting li::before {
content: '›';
position: absolute;
left: 0.25rem;
color: #f9a825;
font-weight: 700;
font-size: 1.1rem;
}

.troubleshooting code {
padding: 0.15rem 0.4rem;
background: rgba(255, 255, 255, 0.08);
border-radius: 4px;
font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
font-size: 0.8rem;
color: #ffb347;
}

.hostname {
display: inline-block;
margin-top: 0.5rem;
padding: 0.25rem 0.75rem;
background: rgba(255, 255, 255, 0.08);
border-radius: 6px;
font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
font-size: 0.85rem;
color: #ffb347;
word-break: break-all;
}
</style>
</head>
<body>
<div class="container">
<div class="status-code">504</div>
<h1>Service Paused</h1>
<p>
This service accepted the connection but did not respond in time. It is
likely paused or under heavy load — it should come back on its own shortly.
</p>
<div class="hostname" id="hostname"></div>
<div class="troubleshooting">
<h2>What's happening?</h2>
<ul>
<li>Wait a few moments and reload — the service may just be temporarily paused or busy.</li>
<li>The container may be under memory pressure; the host can pause it to protect other services on the same machine.</li>
<li>If you're in charge of this service, check its memory usage and look for a request that may be taking too long to complete.</li>
<li>Requests that exceed the proxy timeouts (for example, <code>proxy_read_timeout</code>) can end with this error.</li>
</ul>
</div>
</div>
<script>
document.getElementById('hostname').textContent = window.location.hostname;
</script>
</body>
</html>
Loading