Skip to main content
DevOpsInfrastructure

Nginx maintenance mode that actually works

A maintenance page sounds simple — until your monitoring tool starts reporting false positives, your AJAX requests return HTML no one asked for, and your browser caches the outage long after the app recovers. This is how separating concerns in Nginx makes all three go away.

December 26, 20255 min read

A maintenance page sounds simple — until your monitoring tool starts reporting false positives, your AJAX requests return HTML no one asked for, and your browser caches the outage long after the app recovers. This is how separating concerns in Nginx makes all three go away.

The naive approach breaks monitoring

The obvious solution is an error_page directive at the server {} level — catch any 502/503/504 and return a maintenance page. Done.

Except it's not done, because now /health returns your maintenance HTML too. Your uptime monitor gets a 200 with HTML content, decides the site is up, and you lose the only signal that tells you when the app is actually down.

The fix isn't a workaround. It's a separation of concerns.

Visitor traffic and monitoring traffic have different jobs. Nginx configuration should reflect that.

Separating paths by role

Two paths, two responsibilities:

  • /health → proxied directly to the app, always. No maintenance interception, no error handling, no access logs.
  • Everything else → subject to maintenance logic.
# Monitoring — bypasses maintenance entirely
location /health/ {
    proxy_pass http://localhost:5000;
    access_log off;
}

# All visitor traffic
location / {
    proxy_pass http://localhost:5000;
    error_page 502 503 504 = @maintenance_handler;
}

Now when the app is down, /health returns an honest 503 from the proxy failure. Monitoring tools get a real signal. Visitors get a graceful page.

Handling AJAX correctly

A maintenance page that returns HTML to an AJAX request creates a different kind of breakage — the frontend receives markup it can't parse, and the error handling code that's supposed to show a user-friendly message gets confused HTML instead of JSON.

The fix is to check the request type and respond accordingly:

map $http_x_requested_with $is_ajax {
    default 0;
    "XMLHttpRequest" 1;
}

location @maintenance_handler {
    if ($is_ajax) {
        add_header Content-Type "application/json; charset=utf-8" always;
        return 503 '{"success": false, "message": "The site is currently under maintenance. Please try again later."}';
    }

    root /var/www/maintenance;
    try_files /maintenance.html =503;
}

Regular visitors get the styled HTML page. AJAX requests get a proper JSON 503. Both can handle their response correctly.

The gotcha: static files and cache poisoning

After deploying this, a new problem appeared. When Nginx intercepted a failed request for a .js or .css file during downtime, the browser cached the maintenance HTML response under that asset's URL.

When the app recovered, the browser still had app.js cached as an HTML maintenance page. Scripts failed silently. The site looked broken long after it was actually fixed.

The maintenance handler should never intercept static asset requests. If it does, browsers will cache the wrong content — and that cache outlives the outage.

The fix is an explicit exclusion for static files before the maintenance logic runs:

location ~* \.(js|css|png|jpg|ico|woff2?)$ {
    proxy_pass http://localhost:5000;
    # No error_page here — let static asset failures fail normally
}

Static files bypass the maintenance handler entirely. A missing asset returns whatever the app or proxy returns — but it never gets cached as a maintenance page.

What this solved — and what it didn't

✓ Monitoring tools receive accurate signals — /health is never intercepted by maintenance logic

✓ AJAX requests get machine-readable responses — no broken error handling in the frontend

✓ Static assets are excluded — no cache poisoning after recovery

⚠ This setup handles application-level downtime (app crashes, restarts, deployments). If Nginx itself goes down, both visitors and monitoring go dark — that's a different problem requiring a different layer.

Key takeaways

Put error_page on location /, not server {}. Server-level error handling catches everything, including monitoring endpoints you need to stay honest.

AJAX requests need JSON, not HTML. Checking $http_x_requested_with before responding is the difference between a graceful degradation and a frontend that silently breaks.

Static files should never hit the maintenance handler. The cache poisoning issue isn't obvious until it happens in production — exclude asset paths explicitly before the handler is ever reached.

Separate paths by their role. Visitor traffic, monitoring traffic, and static assets each have different requirements. Nginx configuration that reflects those differences is easier to reason about and harder to break accidentally.