When setting up Nginx as a reverse proxy for Node.js applications, many developers encounter an unexpected behavior: when the backend service (Node.js in this case) is down, Nginx simply returns a 502 Bad Gateway error rather than serving a custom fallback page.

To implement proper fallback handling, we need to leverage several Nginx directives:

proxy_intercept_errors on;
error_page 502 503 504 /fallback.html;

Here's the full configuration that implements a proper fallback mechanism:

server {
    listen 8080;
    server_name mydomain;
    access_log /log/path/logging.log;
    root /path/to/root/;
    
    # Custom error handling
    error_page 502 503 504 /error/index.html;
    error_page 400 401 402 403 404 500 501 /error/index.html;

    location / {
        proxy_pass http://127.0.0.1:1337;
        proxy_redirect off;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        
        # Timeout settings
        proxy_connect_timeout 5s;
        proxy_read_timeout 60s;
        
        # Enable error interception
        proxy_intercept_errors on;
        
        # Health check fallback
        location /health-check {
            access_log off;
            return 200 "OK";
            add_header Content-Type text/plain;
        }
    }

    # Static fallback content
    location /error {
        internal;
        alias /path/to/error/pages/;
    }
}

For more sophisticated fallback scenarios, you can use try_files with multiple fallback options:

location / {
    try_files $uri @nodejs @fallback;
}

location @nodejs {
    proxy_pass http://127.0.0.1:1337;
    # ... other proxy settings ...
}

location @fallback {
    root /path/to/fallback/content;
    try_files /maintenance.html =503;
}

Here's how to implement a maintenance mode that completely bypasses the Node.js backend:

map $maintenance $backend {
    default "http://127.0.0.1:1337";
    "1"    ""; # Empty string triggers error
}

server {
    # ... other server config ...
    
    location / {
        proxy_pass $backend;
        error_page 502 = @maintenance;
    }

    location @maintenance {
        root /path/to/maintenance/pages;
        try_files /maintenance.html =503;
    }
}

Verify your fallback implementation works by:

1. Restarting Nginx: sudo nginx -t && sudo systemctl restart nginx
2. Stopping your Node.js application
3. Accessing your domain:8080 in a browser

When your Node.js application crashes or becomes unavailable, Nginx's default behavior of returning a 502 Bad Gateway error isn't always the most user-friendly solution. Many production systems require graceful fallback mechanisms to maintain user experience during backend outages.

Here's how to properly configure Nginx to serve custom error pages when your backend service is unavailable:

server {
    listen       8080;
    server_name  mydomain;
    access_log   /log/path/logging.log;
    root         /path/to/root/;
    
    # Custom error pages
    error_page   502 503 504 = @fallback;
    error_page   400 401 402 403 404 500 501 /error/index.html;

    location / {
        proxy_pass              http://127.0.0.1:1337;
        proxy_intercept_errors  on;
        
        # Headers for proper request forwarding
        proxy_set_header        Host $host;
        proxy_set_header        X-Real-IP $remote_addr;
        proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
        
        # Timeout configurations
        proxy_connect_timeout   2s;
        proxy_read_timeout      5s;
    }

    location @fallback {
        # Serve static maintenance page
        try_files /maintenance.html =503;
        
        # Alternative: redirect to a different server
        # return 307 https://backup.mydomain.com;
    }
}

For more robust setups, consider these enhancements:

# Health check for backend
location /health {
    proxy_pass http://127.0.0.1:1337/health;
    proxy_intercept_errors off;
}

# Cache fallback responses
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;

# Custom error responses
map $status $status_text {
    502 'Service Unavailable';
    503 'Service Unavailable';
    504 'Gateway Timeout';
}

server {
    error_page 502 503 504 /custom_50x.html;
    location = /custom_50x.html {
        internal;
        return 503 '{"error": "$status_text", "message": "Service unavailable, try again later"}';
    }
}

To verify your setup works:

1. Start your Nginx server
2. Stop your Node.js application
3. Make requests to your endpoint
4. Check that you receive your fallback response instead of the default 502 page